Peter Torr's Blog

Back means back. Not forwards, not sideways, but back

Peter Torr - MSFT — Thu, 06 Oct 2011 20:09:00 GMT

Windows Phone Mango introduces a lot of great new features for developers: alarms & reminders, pinned secondary tiles, deep-linked toasts, and AppConnect to name just a few. One thing that Mango hasn’t changed, however, is the overall navigation structure of Windows Phone’s “Metro” design and the purpose of the hardware back button. I’ve previously blogged about the concept of places and the tyranny of exit buttons, but with the changes in Mango I wanted to provide a refresher and also update with some new guidance for the new scenarios.

You may find this post quite repetitive. That is deliberate; I really want to illustrate the fundamental concepts on the phone, to show the patterns already established by the built-in experiences, and to drive home the need for consistency in marketplace applications in order to maintain a high degree of user satisfaction.

The most critical point to remember is that “back means back” – it is used throughout the phone to do one of two things:

Dismiss transient UI such as alert dialogs, popup menus, pick lists, driving directions, and the SIP
Return to the previous page (place)

(The astute reader might note that a long-press of the back button is also used to bring up the task switching UI, which is a variation on returning to a previous place. It's also used in games to bring up a 'pause' menu, but games are always the exception that prove the rule).

The back button is never used to move forwards to a new page.

The back button is never used to substantially change the content of the current page.

This principle has not changed in Mango. It has not changed with alarms & reminders. It has not changed with secondary tiles or deep-linked toasts. It has not changed with AppConnect. It has not changed at all.

Follow our lead

Let’s look at some examples of built-in phone features and how they relate to the new Mango APIs.

Reminders

If you have an appointment in the built-in Windows Phone calendar and it is set to show a reminder, the phone will popup a reminder at the appropriate time. Tapping on the text of the reminder takes you into that appointment, as you would expect. From that appointment, hitting the Back button takes you back to whatever you were doing before.

It does not take you to the calendar view. It takes you back to what you were doing.

Reminders from marketplace applications should behave exactly the same way. Tapping on the text of the reminder should deep-link into the application to show detailed information, and the Back key should always exit the application and return the user to what they were doing.

Secondary Tiles

Many of the built-in applications allow you to pin secondary tiles. The People hub lets you pin individual people or groups; Zune lets you pin albums, playlists, and artists; maps lets you pin locations; and so on. When you tap on the pinned item, it takes you directly to the contact, album, location, etc. and when you hit the Back button you return to the Start menu.

It does not take you to the main hub or application. It takes you back to the Start menu.

Pinned secondary tiles for marketplace applications should behave exactly the same way. Tapping on a tile should deep-link directly into the content that the user pinned, and the Back key should always exit the application and return to Start.

Toasts

The built-in messaging application shows toasts when you receive an IM or SMS. Tapping on the toast takes you to the appropriate conversation where you can read and optionally reply. From the conversation, hitting the Back button takes you back to whatever you were doing before.

It does not take you to the all-conversations list. It takes you back to what you were doing.

Toasts for marketplace applications - whether they come from Push notifications or from background agents – should behave exactly the same way. Tapping on a toast should deep-link directly to the appropriate application context, and the Back key should always exit the application and return to what the user was previously doing.

App-to-app links

There’s no direct analog of AppConnect for built-in experiences, but there are cases where one application will link to another, such as when you receive an e-mail with an attached Office document or picture – opening the attachment launches the associated application to display the content. From that application, hitting the Back button takes you back to the original application (in this example, e-mail).

It does not take you to the Office hub or the Pictures hub. It takes you back to what you were doing

AppConnect-enabled applications should behave the same way. If the user searches for a movie in Bing and taps on one of the AppConnect results, that application should show content specific to the movie (show times, reviews, streaming options, etc.). Hitting the back key from that page should exit the application and return to the Bing results.

Allowing further exploration

The previous section discussed how the built-in experiences deal with the back button to enable users to quickly “glance and go” at information and then easily and consistently return to their previous activity with the Back button. But what if the user doesn’t want to return to their previous activity? What if they want to stay within the application and continue exploring or using other features?

Using the built-in experiences again as an example, if you pin a group to Start, after tapping on it you can take additional actions such as viewing an individual person’s profile, sending them an e-mail, browsing their pictures, and so on. No matter what other activities you perform, the sequence of pages the user sees as they hit the Back key is predictable and eventually lands them back at the Start menu without any surprises.

Marketplace applications can do exactly the same thing. If you deep-link into an item from any of the extension points mentioned above, it is fine for you to allow further actions to be taken from that point on. But these further explorations must be forward navigations, never backwards. You can use UI affordances such as hyperlinks, buttons, thumbnail images, or other entry points that the user will naturally perceive as forward navigations deeper into the application. And then when they are done and they want to return to what they were doing, they can use the Back button.

As noted above, none of the built-in applications provide a way to get from a deep-linked item back to its “container” hub or application. If you pin a group to Start and tap on it, Back takes you to Start, not to the People hub. In fact, there’s no way to navigate from a pinned group to the all-people list, even via forward navigation. All the actions you can take within the pinned group are scoped to the context of that particular group. The same is true of pinned Zune content (albums, artists, etc.) but pinned map locations are a little different since once you are viewing the map you are free to perform additional searches (note, however, that Back will always take you to the initial pinned location).

Simplifying applications and their navigation structure is a design pattern that we recommend all applications follow, regardless of their high-level design. Keeping the application structure simple and scoping down the actions the user can take avoids confusion and having the user go off “into the weeds.” Nevertheless, sometimes users really do want to move from a single deep-linked item to the full application experience. An example might be a shopping application where the user has both the main application tile and a “wish list” tile pinned to the Start menu. Tapping the main tile launches the application into its normal browse / search UX, but tapping on the wish list tile lands them directly at their wish list. From here, the user can quickly see the items on their wish list, dive into product details to review customer ratings and price comparisons, and perhaps delete items that are no longer desired. All this can be done using the techniques described above to facilitate seamless, consistent, in-and-out behaviour for the wish list. Tapping the tile launches the wish list, and hitting Back returns to Start. Tapping the tile and drilling into an item shows its details, hitting Back once returns you to the entire list, and hitting Back again returns you to Start.

But in this scenario there are some more complicated things the user might want to do though:

Purchase the items in their wish-list by going through a checkout procedure
Add new items to their wish list by browsing / searching the catalog
Engage in free-form discovery, purchase a one-off item, create a new type of list, or perform other actions not directly related to the wish-list

Completing a task

In the first case, the actions are still well-scoped to the original item that was pinned to Start. There might be an AppBar button, for example, that allows the user to purchase the items. The purchase experience may require several steps (especially if the user doesn’t already have a credit card or billing address on-file) and each of those steps might be implemented as a page in your application. While the user is performing the checkout operation, it makes sense for the Back button to return to the previous step. For example, if the user went from the wish list page to the billing address page to the credit card page, pressing Back would return them to the billing address page, then the wish list, then to Start.

Once the user has completed the entire transaction, it doesn’t make sense for the Back key to traverse the (now stale) sub-steps of the purchasing flow - they can’t change their address or credit card number, for example - so those ‘orphaned’ pages can be removed from the back stack. So if the user is presented with the confirmation page, pressing the Back button would return them to the (now empty) wish list, ready for them to add more items or return to Start by hitting Back again.

Constrained exploration related to a task

In the second case, where the user wants to add more things to their wish list, there are a couple of options you might take. The first is very similar to the above approach; instead of the billing / credit / done sequence, you might have a search / results / details sequence, where once the user reaches the details page and hits “add to wishlist” the application automatically navigates back to the (now longer) wishlist, clearing all the items in the process. In this case, Back would exit the application:

Another solution would be the same search / results / details sequence, but after the user hits “add to wishlist” the app merely shows a confirmation that the item has been added, leaving the user to return to the search results or search pane for further exploration:

Either of these approaches should be OK, since it is clear to the user that they have either completed a task (in the first case, similar to the purchase flow) or are still free to explore (in the second case). What’s important is that you don’t allow the user to go off “into the weeds” in such an experience so that they forget where they came from. For example, in the details page of the item above there are no options to find related items or to purchase it directly; the activity is well-scoped to just adding things to the list. (If this page was implemented using the same details page that was used for every-day browsing, you would dynamically remove these elements when in the context of the add-to-wishlist sequence). A concrete example here with a built-in experience is the photo viewer. If you launch the Photos hub and open up an image, the AppBar menu contains all sorts of commands to share, delete, save to favourites, and so on. But if you open a file attachment from an e-mail, there are only two options available to you: save and set as wallpaper. The user is prevented from getting too far off-track from their original task of reading e-mail.

Unconstrained exploration

In the third case, the user decides (for whatever reason) that they want to break out of the context for which they launched the application and just start using your application as if they had launched it from the primary tile. As noted above, none of the built-in applications provide such a feature, so you should think long and hard about whether it really makes sense for your application or whether it would do more harm than good. If you think it will be a common case that the user wants to transition from a deep-linked item (secondary tile, incoming toast, etc.) to an unrelated portion of the application, consider the possibility that you’re exposing the wrong types of things as deep links. Just because the feature is there, doesn’t mean you have to use it.

Nevertheless, there will be legitimate cases where the user wants to go from a deep-linked item into the broader context of the application. I gave one example of this in my Multitasking talk at MIX 11, where I demonstrated a simple “to-do” application that allows the user to remind themselves of things they need to do. In this instance, it is not unreasonable to expect that once the user is reminded to complete task A, they might want to see what tasks B, C, and D are in order to appropriately plan their execution. Note that the rules above about the behaviour of Back still apply. If the user taps on the reminder and sees the detailed page for the to-do item, pressing Back will exit the application and return them to what they were doing.

But if they want to see what other items are still left to do, the application provides them with an additional “home” command that essentially re-sets the application by navigating them to the home view and clearing the back stack.

In this case, pressing Back exits the application rather than taking them back to the original deep-linked item, which is indeed an exception to the rule that “back always goes back” but it is a very specific one for which we can add a third case:

If the user explicitly navigates “home” (using some clear and obvious UI affordance) then the back stack is cleared and Back immediately exits the application

Do what’s right for the user

All of this guidance really boils down to one simple thing, which is letting the user interact with your application in a manner that is most natural for them. To a lesser degree, it’s about respecting your users and trusting them to make the right decisions as they navigate your application and the phone in general. If they popped in to the app to quickly check up on something, the most obvious and consistent mechanism for them to get out again is to hit Back. If they want to drill in deeper, the most obvious and consistent mechanism for them to do that is through forward navigation.

Windows Phone has a different overall user experience than iOS or Android or Symbian or BlackBerry (or any other OS for that matter). The way a user interacts with your application on another platform may not translate well to how they would interact with your application on Windows Phone. And whilst it might seem logical to say “users who move from other OSes to Windows Phone will be confused if apps work differently”, remember that the vast majority of smart phone purchases in the future will come not from people switching from one OS to another, but from people who have never owned a smartphone before and, in many cases, have never owned a PC before either. These are your future customers and they have no pre-conceived notions of how apps “should” or “should not” work; they will simply notice which apps do or do not work well on the phone they choose to buy. In other words, familiarity with the behaviour of other smartphone OSes is not a good excuse for building poor Windows Phone experiences.

Some implementation tips

Guidance itself isn’t worth much when you’re in the trenches pounding out code, so how about some examples? Luckily for me, I’ve already published code that is applicable to this scenarios before, and our documentation already covers these topics with conceptual articles and samples. Yay for not having to write more sample code! :-)

In particular, the aforementioned alarms and reminders post includes code to conditionally display a “home” button on a deep-linked page and how to clear the backstack such that the Back key works as the user would expect. This technique works for reminders, deep-linked toasts, and secondary tiles. There is also a complete “how-to” article on MSDN that explains this topic in detail, and the new Mango backstack APIs should be able to replace any use of the old non-linear navigation service in existing Windows Phone applications.

Another earlier post on redirecting your first navigation might be helpful for cases where your application is launched with a set of parameters, such as from AppConnect. By adding a UriMapper to your application and pattern-matching on the types of parameters that will be sent, you can bypass any interstitial screens and navigate directly to the right content in your application. There’s a full sample project included in the documentation page for AppConnect that shows exactly how to do this.

BUILD 2011 demos

Peter Torr - MSFT — Sun, 18 Sep 2011 05:01:00 GMT

[Update 9/21]

Just got back from //BUILD in Anaheim, and it was a great conference to be at. I presented "Multitasking in Windows Phone" for what seemed like the 100th time, and the slides + video are up on channel 9 but unfortunately the video did not record the slides / demos until about 25 minutes into the video. I've asked to see if they can fix it but I am not hopeful. Sorry for those of you that can't see what's going on :-(

Below I've attached the sample code I used in the demos - basically the same as other content I've posted on the blog, so no new commentary required.

P.S. Thanks to Ginny who - for some strange reason :-) - seems to come to all my talks, no matter how repetitive that must be. You must know them all by heart now. Thanks for the support, I appreciate it!

Multitasking video on The Knowledge Chamber

Peter Torr - MSFT — Fri, 05 Aug 2011 04:55:59 GMT

If you already follow my blog, you probably know everything you need to know about Mango's multitasking support... but just in case you don't, you can check out a video I did with Robert Hess over at Channel 9.

http://channel9.msdn.com/Shows/The+Knowledge+Chamber/Peter-Torr-and-Application-Multi-Tasking-on-Windows-Phone-Mango

Thanks Robert!

Background Agents - Part 3 of 3

Peter Torr - MSFT — Wed, 13 Jul 2011 03:45:00 GMT

In Part 1 we looked at a simple app to get tweets from Twitter, and in Part 2 we looked at the AsyncWorkloadHelper library. In this final part, we'll look at a couple of the other helper libraries in the project that you might find useful. As before, the code can be found at the end of Part 1. This post will hopefully be the shortest of the three since I am tired and I want to post this stuff already! :-)

The TwitterLibrary library

The first helper library we'll discuss is TwitterAccess. I'm sure there are a million twitter libraries out there, and the world probably needs a million-plus-one-th library like it needs a hole in the head, but whatevz. I wanted to code one up myself! This library is basic and supports simple unauthenticated searches on Twitter for search terms. The API looks like this, and I won't bother explaining how it works (hint, look here).

An example of using the library to get a tweet can be seen in Part 2 (or you could just read the code ;-) ).

Oh all right, stop twisting my arm already. Here's a simple example:

/// <summary>
/// Asynchronously loads the tweets with the given search term
/// </summary>
/// <param name="searchTerm">The search term</param>
public void LoadTweetsWithSearchTermAsync(string searchTerm)
{
  TwitterHelper.GetAllTweets(searchTerm, tweets =>
    {
      ObservableCollection<Tweet> temp = new ObservableCollection<Tweet>();
      foreach (var tweet in tweets)
        temp.Add(tweet);
 
      Deployment.Current.Dispatcher.BeginInvoke(
        delegate
        {
          Items = temp;
        });
    });
}

Nothing worth explaining here. Next!

The ShellUiHelpers library

This one's a bit more interesting; it has a simple helper and a more complex helper.

The simple helper is ToastHelper, a thin wrapper around the ShellToast API that lets you pop toasts for the user. The interesting thing that it does is supress toasts if the user is asleep (or, more accurately, if the current system time is a time when we assume the user might be asleep). Nothing fancy but it helps with the Spousal Approval Factor.

The more complex helper is TileHelper, which is a more complex wrapper around the ShellTile APIs that can composite images for the front and back images of a tile. Given a call such as this, it performs a bunch of work on your behalf:

TileHelper.UpdateTile(new ExtendedTileData
  {
    FrontText = "latest tweet",
    FrontTitle = TweetSearchTerm,
    BackText = tweet.TweetText,
    BackTitle = tweet.AuthorAlias,
    BackImage = tweet.AvatarUri,
  });

First, it checks if you are calling on the Dispatcher thread or not; you can't do this because of the blocking nature of the API (basically, UpdateTile acts as a synchronous operation, but it dispatches work to the UI thread in order to compose the bitmaps. If you were on the UI thread already, you would block waiting for the UI operation, but it is waiting to be dispatched on the same thread... so you have a deadlock).

Next, it uses the AsyncWorkHelper APIs we discussed in Part 2 to call two methods in parallel, GetBackgroundImage and GetBackBackgroundImage. These two methods take the metadata from the ExtendedTileData class and compose them into two bitmaps, which are then saved as JPEGs and used for the tile backgrounds.

GetBackgroundImage gets the "front" background image. Because the default tile template doesn't support text on the front of the tile (just a small Title), this method composes the background.png found in the application's XAP (the default tile image created in a new project) with a rendered text string (the FrontText property, above). It fades out the background a bit to make the text more readable, but you can change this by updating the FRONT_IMAGE_OPACITY constant. The code uses a shared helper function to compose the image:

/// <summary>
/// Composes a simple tile image and writes it to disk
/// </summary>
/// <param name="background">The background image</param>
/// <param name="opacity">Desired opacity of the background image</param>
/// <param name="text">Optional text to render into the image</param>
/// <param name="baseFileName">The base filename to use (no directory or extension)</param>
/// <returns>The actual full path to the file as written to disk</returns>
static string ComposeTileAndWriteToDisk(BitmapImage background, double opacity, string text, string baseFileName)
{
  // Create a container of the correct size
  Grid container = new Grid();
  container.Width = TILE_WIDTH;
  container.Height = TILE_HEIGHT;
 
  // Add the text, if necessary
  if (String.IsNullOrWhiteSpace(text) != true)
  {
    container.Children.Add(new TextBlock
    {
      Text = text,
      TextWrapping = TextWrapping.Wrap,
      Foreground = new SolidColorBrush(Colors.White),
      // The font size, line height, and margin have all been chosen to match the shell's rendering of text on tiles
      FontSize = 30,
      LineHeight = 32,
      LineStackingStrategy = LineStackingStrategy.BlockLineHeight,
      Margin = new Thickness(12, 10, 8, 34)
    });
  }
 
  // Add the background
  container.Background = new ImageBrush
  {
    ImageSource = background,
    Opacity = opacity,
  };
 
  // Force the container to render itself
  container.Arrange(new Rect(0, 0, TILE_WIDTH, TILE_HEIGHT));
 
  // Write the image to disk and return the filename
  return WriteShellTileUIElementToDisk(container, baseFileName);
}

This code is pretty straight-forward; basically it creates a 173 x 173 pixel Grid, adds the text (if any) to it as a child element, then sets the background to the supplied image. Trial and error led to the values you see above for the text size and margins. It then renders the image to disk using the SaveJpeg extension method (via the WriteShellTileUIElementToDisk helper) and returns the full path to the rendered file. Note that for shell tile background images, the files must be saved in the /shared/shellcontent/ folder of IsoStore, which is set as the constant SHARED_IMAGE_PATH in the code.

The GetBackBackgroundImage method does something similar, but instead of using the background.png already in the XAP, it needs an additional async operation to download the image specified by BackImage first. The caller of UpdateTile doesn't need to worry about the extra async calls though because the AsyncWorkHelper is waiting for it:

// Must run on the dispatcher thread (due to use of BitmapImage)
Deployment.Current.Dispatcher.BeginInvoke(delegate
{
  BitmapImage image = new BitmapImage();
  image.CreateOptions = BitmapCreateOptions.None;
 
  // Handle both success and failure cases with a completion delegate
  image.ImageFailed += (o, e) => CompleteGetBackBackgroundImage(tileData, null, token);
  image.ImageOpened += (o, e) => CompleteGetBackBackgroundImage(tileData, o as BitmapImage, token);
 
  // Set the source to the remote URI, which will trigger the download
  image.UriSource = tileData.BackImage;
});

Here CompleteGetBackBackgroundImage basically just calls ComposeTileAndWriteToDisk and then calls NotifySuccess.

Beware of the '@' sign

One final tip for those of you writing out tile content - especially it if comes from Twitter, which makes heavy use of the '@' symbol: If your tile's BackContent property is set to a string that begins with an @ sign, the system will treat it as a resource lookup ID (and fail), resulting in your tile displaying something like "@\Application\Install\{GUID}" instead of your intended string.

To combat this, you can use some code like this:

// Set the back of the tile info
// Be careful to escape leading '@' signs so they are not confused for resource strings
string backText = tileData.BackText;
if (backText.StartsWith("@"))
  backText = ZWSP + backText;

where ZWSP is the Unicode zero-width space character, defined like this:

/// <summary>
/// Zero-Width-Space; used to escape '@' sign in content
/// </summary>
const char ZWSP = (char)8203;

This will ensure that the first character is not an @ sign, but it also isn't visible so won't affect your output.

That just about wraps it up! Remember, you can find the code in Part 1 or you can read about the AsyncWorkHelper in Part 2.

Enjoy!

Background Agents - Part 2 of 3

Peter Torr - MSFT — Wed, 13 Jul 2011 03:34:00 GMT

In Part 1 we looked at a simple Windows Phone application that used a background agent to periodically show a toast and / or update a tile when a new tweet was found for a particular search term. The code we are discussing in this post can be found at the end of that post.

Part of the contract of a background agent is that you must call NotifyComplete or Abort exactly once when your agent has completed processing. This is pretty easy if you have a sequential set of synchronous steps to complete, like reading and writing from IsoStore, but it is harder when you have one or more asynchronous operations or when you need to throw work over to the Dispatcher thread, since you can't rely on things like try-catch blocks to handle errors.

It's possible (but not desirable) to try and serialize the asynchronous operations with simple WaitHandle operations, but doing that might mean you run out of your agent runtime before all the operations complete. Better to do them in parallel, and then have a simple way of waiting until they have all completed (successfully or otherwise) and then calling NotifyComplete / Abort as necessary.

Such was the case with the Twitter background agent. It performs network downloads to get tweets from twitter.com, and it also needs to dispatch to the UI thread to compose the background tile image. Initially I used a ManualResetEvent and did something like this:

ManualResetEvent evt;
 
// Main agent code
void AgentCode()
{
  evt = new ManualResetEvent(false);
 
  DoAsyncWork();
  evt.WaitOne();
 
  evt.Reset();
  DoMoreAsyncWork();
  evt.WaitOne();
 
  NotifyComplete();
}
 
void DoAsyncWork()
{
  // Lots of work on another thread...
 
  evt.Set();
}
 
void DoMoreAsyncWork()
{
  // Lots of work on another thread...
 
  evt.Set();
}

It works, but it's not terribly efficient. We could be doing the second bit of async work at the same time as the first one, especially if they both involve something like network access that spends most of its time waiting for bits anyway. What we need is a helper library to let us queue up a bunch of async work, set it all free, and then wait for them all to report done-ness. Now, you could consider using the Async CTP, but it's still a "technology preview" (ie, not a shipping product) and it has issues with background agents right now because the helper library references XNA (which is a no-no for agents).

Enter the AsyncWorkloadHelper library!

The AsyncWorkloadHelper library

The background agent project contains a library named AsyncWorkloadHelper. It is pretty simple; the public API looks like this:

Both classes are generic and require two types:

TParam, the type of the parameter that you will pass to your async methods. Use object if you have varying parameter types
TResult, the type of the return value of the async methods. Again, use object if you have varying return types

Using the library is very simple; here's some code from the twitter agent itself that generates live tile background images:

// Asynchronously generate the bitmap images (front and back)
var workManager = new AsyncWorkManager<ExtendedTileData, string>();
var backgroundImageWorker = workManager.AddWorkItem(GetBackgroundImage, tileData);
var backBackgroundImageWorker = workManager.AddWorkItem(GetBackBackgroundImage, tileData);
 
// Wait for the async operations to complete
workManager.WaitAll();
 
// Set the front of the tile
if (backgroundImageWorker.Error == null)
  data.BackgroundImage = new Uri(ISOSTORE_SCHEME + backgroundImageWorker.Result);
else
  data.BackgroundImage = EMPTY_URI;

It's pretty self-explanatory:

Create an instance of the AsyncWorkManager with the appropriate types parameters
Call AddWorkItem for each work item you intend to execute

The first parameter is the delegate that will do the work
The second parameter is the parameter to pass to the method
The return value is a WorkloadInfo object you will use later

Call WaitAll to wait for them all to complete (there's also a version with a timeout if you don't want to wait indefinitely)

You could also listen for the WorkComplete event if you like

Once work is done, check the Error property of the WorkloadInfo

If it is null, the result is valid and you can get it via the Result property
Otherwise, you can do something with the Error itself

That's it! The methods that are called by the worker - in this case, GetBackgroundImage and GetBackBackgroundImage - only have one responsibility: to call NotifySuccess or NotifyFailure when they are done. For example, here's the complete listing for GetBackgroundImage:

/// <summary>
/// Asynchronously gets the background image for a specific tweet
/// </summary>
/// <param name="tileData">The tile data to add to the image for</param>
/// <param name="token">The completion token</param>
static void GetBackgroundImage(ExtendedTileData tileData, WorkloadInfo<ExtendedTileData, string> token)
{
  // Must run on the dispatcher thread (due to use of BitmapImage)
  Deployment.Current.Dispatcher.BeginInvoke(delegate
  {
    try
    {
      BitmapImage bi = new BitmapImage();
      bi.CreateOptions = BitmapCreateOptions.None;
 
      // Pull the standard background image out of our app package
      bi.SetSource(Application.GetResourceStream(new Uri("background.png", UriKind.Relative)).Stream);
 
      // Compose the image and write to disk
      string fileName = ComposeTileAndWriteToDisk(bi, FRONT_IMAGE_OPACITY, tileData.FrontText, "frontimage");
 
      // Complete the async operation
      token.NotifySuccess(fileName);
    }
    catch (Exception ex)
    {
      token.NotifyFailure(ex);
    }
  });
}

This is pretty simple:

The signature for the method is: TResult MethodName(TParam param, WorkloadInfo<TParam, TResult> token), where the the type params are dictated by the AsyncWorkManager that is being used

In this case, TParam is ExtendedTileData and TResult is string.

In this case, the code has to be dispatched to the UI thread since we'll be composing some bitmap images
The async code is wrapped in a try-catch; if it fails we will call NotifyFailure with the error (which will propagate back to WorkloadInfo.Error)

If the synchronous code fails, the error is automatically caught by the library

Assuming nothing goes wrong, we call NotifySuccess, passing in the result of the function

Of course the "interesting" bit is tied up in that ComposeTileAndWriteToDisk method, but it is a synchronous method that, well, composes some content into a tile image and writes it to IsoStore, returning the full filename.

How it works

The implementation of the AsyncWorkManager is pretty basic. Of course you can check out the code for yourself, but in a nut-shell it works like this:

There is a counter, outstandingItems, that counts how many remaining items there are to complete. This starts at zero.
There is an event, startEvent, that is used to "hold back" all the work until the client is ready for them to start. This starts non-set.
There is another event, completionEvent, that is used to wait until all work is complete. This starts non-set.
Calling AddWorkItem increments outstandingItems and kicks off a ThreadPool thread that first waits for startEvent to be set, then calls the associated method
Calling WaitOne implicitly calls Start, then waits for the completionEvent to become set.
Start sets startEvent, releasing all the threads
As each work item completes, it calls NotifySuccess or NotifyFailure. These stash the appropriate values into the WorkloadInfo class and then call the internal CompleteWorkItem method
CompleteWorkItem decrements outstandingItems, and if the value is zero then it sets the completionEvent
The completionEvent releases the WaitOne call and also raises the WorkComplete event

So no rocket science, just a small set of framework code to make things easy for you.

That said, this code isn't particularly well tested, nor have I really used it outside of this project. For example, I don't really know if making the API generic has value (it did for me, since the methods I wanted to call had the same signature) but maybe that's too messy and object would just work better in general. I also don't know how it really performs in error conditions or with large numbers of work items (more than fit into the thread pool, for example)... use at your own risk!

As a reminder, you can get the project at Part 1. Next up, Part 3.

Background Agents - Part 1 of 3

Peter Torr - MSFT — Mon, 11 Jul 2011 07:31:00 GMT

This post has (errr, "These posts have") been a long time coming. They are based off the Mix 11 and TechEd 2011 sessions I gave a loooooong time ago, but despite my best efforts I've not been able to post anything to my blog for some time. Partly it was due to a family vacation in Yellowstone National Park (go there! it's incredible!) and partly it's due to being rather busy getting the finishing touches on Mango and preparing for what's next. But mostly it's due to the fact that every time I sit down to blog about it, I add some new feature to the code or make it more extensible... this is almost (almost!) a complete app at this stage, but it's not quite good enough to put in the marketplace.

This series of three posts will demonstrate the basics of background agents in Mango, and will throw in a couple of helper libraries as well (that is what parts 2 and 3 are about). The sample app, as seen in the aforementioned Mix / TechEd demos, is a simple Twitter viewer that uses a background agent to periodically show a toast and update the application's tile if there are new tweets since the last tame the app or the agent ran.

The foreground app

The foreground app for this particular demo isn't very interesting. It shows a list of recent tweets for a given search term (the hard-coded default is, of course, wp7dev) and if you tap on any of the items it shows the tweet in full, complete with the user's background image and the ability to follow any links in the tweet. It's not smart enough to link-ify #hashtags or @usernames, etc. so it doesn't suffice as a real twitter client; it's just enough for someone to casually keep up with a search term.

The app looks like this:

Nothing too special. The only interesting bit on the app is the "enable agent" check box at the bottom-left of the screen, which is where the magic happens, as they say.

When you click the "enable agent" button, it runs this code:

/// <summary>
/// Starts the search agent and runs it for 1 day
/// </summary>
private void StartSearchAgent()
{
  PeriodicTask task = new PeriodicTask("twitter");
  task.Description = "Periodically checks for new tweets and updates the tile on the start screen." +
    " Will also show a toast during normal 'waking' hours (won't wake you up at night!)";
 
  task.ExpirationTime = DateTime.Now.AddDays(1);
  try
  {
    ScheduledActionService.Add(task);
  }
  catch (InvalidOperationException)
  {
    MessageBox.Show("Can't schedule agent; either there are too many other agents scheduled or you have disabled this agent in Settings.");
  }
}

The code is pretty straightforward:

Create a PeriodicTask, which is the main class you use to describe the behaviour of the background agent. A periodic task runs every 30 minutes for about 25 seconds, give or take.
- If you'd prefer to run for much longer - but only when the phone is plugged in and on WiFi - you can create a ResourceIntensiveTask instead
Give the task a Description, which will show up in the system UI under settings -> applications -> background tasks. This text will explain to the user what your agent is doing and will help them determine whether or not to disable the agent at some future point in time.
Set the ExpirationTime for 1 day from now. You can specify an expiration date up to 14 days in the future, but in order to be kind to the batter this app defaults to 1 day.
Try to add the task to the ScheduledActionService. This might fail if the user has disabled the agent in settings or if there are already too many other agents running on the phone.
- There's not really a good way to tell which it is, but the good new is that the remedy is always to tell the user to go to the settings page and enable your agent (and / or disable some other agents).

And that's all there is to it! Now the system will happily run your agent every ~30 minutes and let it do its thing. Hooray!

The background agent

The agent is also pretty simple. As you can read about in the docs, you basically add a background agent project to your solution and then implement the work you want to do in the OnInvoke method of your class. A few notes about agents up-front:

Your agent must derive from ScheduledTaskAgent and you must override OnInvoke
Your agent must be correctly registered in WMAppManifest.xml of the foreground project
- Visual Studio does this for you automatically, but if you change the name of the class or of the project you will need to update the XML file
- Cheat sheet: Specifier = ScheduledTaskAgent, Source = [assembly name], Type = [fully qualified type name], Name = [whatever you want]
Your agent project (and any projects it references) must be referenced by the foreground project, even if you never use it (this is so that it is correctly added to the XAP)
Your foreground app never explicitly calls into the agent (they are separate processes) but if you want you can instantiate an instance of the agent class inside your foreground app in order to share code (using a shared library might be a better approach, though)

Just in case you missed it (and for search-engine-friendliness):

If you change your agent's project name, namespace, or class name, you must update WMAppManifest.xml for the new metadata
If you reference another assembly from the agent, you must also reference it from the foreground app to ensure it makes it into the XAP

If you fail to do this, your agent will not load at all. If you run it under the debugger with the break on all exceptions turned on, you will get a FileNotFoundException stating that it can't find your assembly or one of the assemblies it relies on.

Anyway, back to our story. The agent's work looks like this (we'll get into the guts of it later):

/// <summary>
/// Called by the system when there is work to be done
/// </summary>
/// <param name="Task">The task representing the work to be done</param>
protected override void OnInvoke(ScheduledTask Task)
{
  // Read the search term from IsoStore settings; in a more complex scenario you might
  // have multiple tiles and read each tile's term from a different setting
  IsolatedStorageSettings settings = IsolatedStorageSettings.ApplicationSettings;
  TweetSearchTerm = settings["searchTerm"].ToString();
 
  // Get the tweets from the library
  TwitterHelper.GetFirstTweet(TweetSearchTerm, tweet =>
    {
      // Don't do any work if this is invalid or the same as the most recently-seen tweet
      if (tweet.Id != Tweet.InvalidId && tweet.Id != settings["lastTweetId"].ToString())
      {
        settings["lastTweetId"] = tweet.Id;
        settings.Save();
 
        // Show the toast
        ToastHelper.ShowToast(tweet.AuthorAlias, tweet.TweetText, new Uri("/DetailsPage.xaml?id=" + tweet.Id, UriKind.Relative));
 
        // Update the tile
        TileHelper.UpdateTile(new ExtendedTileData
          {
            FrontText = "latest tweet",
            FrontTitle = TweetSearchTerm,
            BackText = tweet.TweetText,
            BackTitle = tweet.AuthorAlias,
            BackImage = tweet.AvatarUri,
          });
      }
 
      // Done!
      NotifyComplete();
    });
}

What's going on here?

First we get the search term from the ApplicationSettings (this is set in the foreground app)

As noted above, this is currently set to wp7dev

Then we call a handy-dandy method GetFirstTweet to retrieve the first tweet that matches our search term
- This is an asynchronous call, of course, since it goes out to the web
When the call returns, we check if the tweet is valid and whether it is different from the last tweet we saw (which is also retrieved from ApplicationSettings)
- If the tweet is invalid or not new, we skip to the end
The current tweet is saved as the last-seen tweet, so we don't show it again next time
We use a helper method to show a toast to the user with the tweet's author and text. We also use a deep link into the application so that tapping on the toast will launch directly into the details page for that toast
- The same technique as used in the alarms and reminders example is used to show a "home" button in the UI in this case
We use another helper method to update the primary tile with the tweet information, including the author's avatar (this will appear on the back of the tile)
Finally, we call the all-important NotifyCompletemethod to let the system know we completed successfully.
- If we had hit an unrecoverable error, we could call Abort instead

The importance of calling NotifyComplete at the right time cannot be overstated!

Failure to call NotifyComplete at all will cause the system to think you timed-out, and then in the foreground if you query LastExitReason you will get a failure code ExecutionTimeExceeded
Calling NotifyComplete too early will immediately terminate your process, leaving any remaining work on background threads incomplete (although the system will happily report that you Completed successfully!)

Luckily there is a simple way to deal with this, as we shall see in Part 2 of the post.

A handy tip for agent debugging

One of the problems with debugging agents is that the very act of using the debugger changes the way your agent executes. In particular, when the debugger is attached both the runtime quota and the memory quota are ignored, leaving you with infinite time and memory to (ab)use. This is necessary for the debugger to work correctly (imagine trying to complete a debug session in only 25 seconds!) but introduces issues if the thing you're trying to debug is a memory and / or execution time issue.

Now back in the olden days - when we used to have to walk to school uphill in both directions - we didn't have fancy-schmancy graphical debuggers. We had printf! Now printf (or its modern debugging equivalent, Debug.WriteLine) doesn't really help with an agent if you can't have the debugger attached, so there's not much you can do. Obviously you can write out logs to a log file and then read them off the device with the Isolated Storage Explorer tool, or if you're brave enough you can enable console spew from the emulator, but if you just want to display a tiny bit of text - like, say, the amount of memory you're currently using or the amount of time you've been executing... why not use a toast?

The agent includes a method WriteDebugStats that is used to write some memory statistics to a toast (and to a tile for good measure!). Because toasts "stack up" in the shell and are displayed for several seconds before being replaced by the next toast, you can actually queue up several messages inside toasts that can be used to convey debug information while not under the debugger.

The method looks like this, using the same helper methods as before to show the toast and a tile update (the memory values are all based on calls to ApplicationPeakMemoryUsage API):

/// <summary>
/// Writes out debug stats to a toast and a secondary tile (if it exists)
/// </summary>
void WriteDebugStats()
{
  const double ONE_MEGABYTE = 1024 * 1024;
  double initial = (double)initialMemory / ONE_MEGABYTE;
  double beforeTile = (double)beforeTileMemory / ONE_MEGABYTE;
  double final = (double)finalMemory / ONE_MEGABYTE;
  TimeSpan duration = DateTime.Now - startTime;
 
  // Show a toast
  ToastHelper.ShowToast("Mem / time", string.Format("{0:#.#}-{1:#.#}-{2:#.#}MB / {3:#.#}s", initial, beforeTile, final, duration.TotalSeconds), null);
 
  // Update the debug tile (if it is pinned)
  TileHelper.UpdateTile("DEBUG_TILE", "debug info", "debug info", string.Format(TweetSearchTerm + ": {0:#.#}MB, {1:#.#}s", final, duration.TotalSeconds));
}

If the app is running in debug mode, it will display a "debug" button on the main page that will pin a secondary tile to start that is used to display the debug info.

Another handy hint - use the new LaunchForTest API to launch your agent whenever you want - this replaces the old (Beta 1) behaviour of launching the agent whenever Add or Find was called and the debugger was attached (it was a rather annoying "feature"). You can even call LaunchForTest from the background agent itself, letting it run in perpetuity (but, of course, only on side-loaded dev projects; a shipping marketplace app can't call this method). If you run the project in "Debug" mode you will see button that lets you run the agent immediately (there are is a short delay giving you enough time to exit the app so that the toast will appear).

That's it for Part 1 - the project is zipped up below, and we'll discuss more of the project in parts 2 and 3.

Alarms and Notifications in Mango

Peter Torr - MSFT — Sat, 28 May 2011 23:50:00 GMT

Here's the first of several posts about the new multitasking features in Windows Phone Mango. Alarms and Notifications is a good place to start because it is the simplest of the new multitasking features (outside of Fast App Switching, but that's not really an API) and it doesn't require running code in the background; it just leverages a system service to notify the user when a specific time is met.

If you haven't seen it yet, you can watch my Mix 11 video (or the Tech Ed version, which includes more conceptual stuff and less code).

The sample application is a very basic "todo" application that is impossible to build on Windows Phone 7 due to the need to display a reminder at a future point in time (at Mix the example was a cake-baking app :-) ). It isn't very functional and it isn't very pretty, but it illustrates the core concepts needed to use the Alarms and Reminders service.

Here are a couple of screenshots

The code is provided below in a ZIP, but let's look at the salient bits of code.

Setting up the reminder

When you click the "remind me!" button in the item detail screen, the following piece of code runs (where item represents the ViewModel item that is bound to the page instance):

// Setup the reminder
Reminder r = new Reminder(item.Title);
r.Title = item.Title;
r.Content = item.Description;
r.BeginTime = DateTime.Now.AddSeconds(15); // item.DueDate;
r.ExpirationTime = r.BeginTime;
r.NavigationUri = NavigationService.CurrentSource;
 
// Add it to the service
ScheduledActionService.Add(r);

Reminder is a new type in Mango that represents a possibly-recurring reminder that behaves just like the calendar reminders built-in to the phone (you can also use an Alarm, which is similar to a reminder but has slightly different behaviour - you should experiment with it and explore via IntelliSense).

The constructor takes a string which is used as the Name for the reminder. This lets you locate the reminder later on to check if it has expired or not, to remove it if it's no longer necessary, and so on. Note that you can create many reminders - in this example, one for each ToDo item.

The Title and Content properties are used to populate the text in the reminder when it pops up on-screen, like this:

Note that you do not have control over the Snooze options, nor whether or not the "snooze" and "dismiss" buttons appear - they are all controlled by the system.

The BeginTime is the time that the reminder first goes off (in this case, we set it to 15 seconds from now so that it is easy to demo), and if you set the RecurrenceType of the reminder (not used in this sample) it also determines the beginning of the reminder pattern (daily, weekly, etc,)

The ExpirationTime is the time that the reminder should stop being scheduled. In this example it doesn't affect the UI (since we are not creating a recurring reminder) but it will be used later on in the code to determine whether we should clean-up old reminders or not. In general you should set this for all reminders since it will make your code easier.

The NavigationUri specifies the page to launch if the user taps on the reminder title / content when the reminder fires (little-known fact about WP7 is that this works even for the built-in calendar app, but only if the phone isn't currently locked). If you don't specify a URI, your app will just launch normally. Note that if your app is currently in the foreground when the reminder is fired, tapping on the title / content will dismiss the reminder but will not cause a navigation (since your app is already running).

Finally we add it to the ScheduledActionService, which will do the job of firing the reminder when the BeginTime is reached (note that the reminders are only accurate to the nearest minute, and in the beta the emulator gets less accurate over time... just close and re-open it if you find reminders are not firing at all).

Cleaning up the reminder

It's just as important to clean things up as it is to create them! The sample uses a simple helper method to do this every time a detail page is navigated to:

// Removes the reminder if it has expired
void CleanupOldReminder(ToDoItem item)
{
  var reminder = ScheduledActionService.Find(item.Title);

  // If found and it has expired, remove it
  if (reminder != null && reminder.IsScheduled == false)
    ScheduledActionService.Remove(reminder.Name);
}

Now we see why setting ExpirationTime is important - it let's us check the IsScheduled property to know whether to delete the reminder or not, using the aptly-named Remove method.

Dealing with deep links

The only other useful thing in this sample is how it deals with the deep links into the application from the reminders. As I've blogged several times before, Windows Phone uses the hardware Back key to navigate to the previous "place", and in the case where the user navigates directly into the details page (as is the case if they tap on the reminder) then the previous place will not be the main screen of the application, but rather whatever the user was looking at before (another app, the start menu, etc.). To see how this works on the phone, you can create deep links in the built-in apps and note that when you tap on the tile and then hit back, you return to the start menu. Examples of built-in pinnable items are contacts, albums, and playlists.

Nevertheless, some applications will benefit from enabling the user to navigate from the deep-linked page into the main UI of the application (none of the built-in apps do this, but you can). In this case, after a reminder has fired in the ToDo app, maybe you want to see what other things are left on your list. To do this, we introduce a "home" button on the detail page, but only display it if the Back key won't work:

// Only show the GoHome button if there is nothing else on the backstack (ie, this is the first page)
if (NavigationService.CanGoBack != true)
  goHomeButton.Visibility = Visibility.Visible;

Here we check CanGoBack - if it is true, that means the user is navigating the application normally and the Back key will take them home. But if it is false, that means they deep-linked into the page from the reminder and can't use the Back key - instead we'll forward-navigate home. In order to avoid having the detail page on the back stack (which might be confusing), we'll signal to the main page that we want it to clear up the backstack:

// Navigate to the home page, and tell it to clear the stack
void GoHomeClick(object sender, RoutedEventArgs e)
{
  NavigationService.Navigate(new Uri("/MainPage.xaml?clear=yes", UriKind.Relative));
}

Then inside the main page, we use a new method RemoveBackEntry to clean up the old entry if it's been requested by the calling application:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
  // If this is a new navigation AND the caller has asked us to remove them from the stack, then do so
  if (e.NavigationMode == NavigationMode.New && NavigationContext.QueryString.ContainsKey("clear"))
    NavigationService.RemoveBackEntry();
}

Also note that we've added the NavigationMode property on to all the navigation-related EventArgs, making it easier to do things like this (and manage animations, etc.)

And that's about it!

Mango samples coming soon, no really!

Peter Torr - MSFT — Tue, 24 May 2011 01:42:00 GMT

Now that the consumer features of Mango have been announced and the beta developer tools have been released, it's time to make good on my promise to make the Mix / TechEd sample code available to all. I'll also try and post the push notifications code from TechEd that I borrowed from Tom Fennel.

I am in the process of doing this, but it will take a little while; first I need to install the beta software on my home PC to make sure all the demos work just fine (vs from the build I used at TechEd) and then I need to clean things up, add comments, and write a suitably informative post to go with the code.

In the meantime, you can download the tools, crack open the docs, and start partying on the APIs yourself! If you haven't already watched the talks from Mix or TechEd, you can find them here:

Multitasking at Mix (all code)
Multitasking at TechEd (half slides, half code); thanks to Darin Miller for the original slides (you can watch his Mix version here)
Push Notifications at TechEd (mostly slides); thanks to Thomas Fennel for the original slides and code (you can watch his Mix version here)

Note that Jesse Liberty has beaten me to the punch and already posted a blog entry based on my first Mix demo (notifications and clearing the back stack).

"Mango" posts coming soon!

Peter Torr - MSFT — Thu, 21 Apr 2011 20:54:59 GMT

Just a quick note - the recorded sessions from Mix are available on Channel 9. I will be posting more on some of the new Mango features soon... still trying to dig out from under the pile of e-mail I received while in Vegas! Also I will get the demo code out to you when the tools are available, if not before (depends on how much "free time" I have to polish it all).

For those of you who were at Mix (or have seen the videos), maybe this post makes more sense now... and maybe also this one.

Stay tuned!

I was joking about the penny, but how about some tombstoning sample code?

Peter Torr - MSFT — Tue, 22 Mar 2011 02:50:00 GMT

Thanks to everyone who posted on the previous post about tombstoning in Windows Phone 7. It was actually quite surprising to see the positive comments about tombstoning (both on the blog and privately through e-mail) where developers are saying they appreciate the feature or don't consider it a huge burden. Of course not everyone thinks that way; tombstoning can be hard to get right if you are porting an existing app from elsewhere and have an app design that doesn't deal well with places, or if you build a complex app and then try and implement tombstoning as an afterthought, or even if your application state is just flat-out complex (like many games) or is hard to recreate in a hurry.

As to how to do it with the least amount of pain: our general advice is to rely on databinding to bind your UI to a ViewModel, and then serialize your ViewModel into the page state (for transient data) or to Isolated Storage (for permanent data). Of course there are some bugs or "missing features" in our platform that means that not everything works as smoothly as it should. A few examples of things that don't get saved automatically (or do get saved but are hard to restore):

Content of text controls if they have focus at the time of deactivation
Scroll positions of ListBoxes and ScrollViewers
Position and state of MediaElement

The project attached to this post serves both as an example of how to use the databinding pattern to save state (for those not familiar with it) and also as a vehicle for a handful of extension methods to help cover the cases above. One thing that is not in the sample project is restoring the focused control or text selection state; I've seen that done in some places but I don't think it is necessary to do this in general; none of the built-in experiences do it as far as I can tell unless those that are almost wholly concerned with text entry (like e-mail compose).

One thing - the sample project tries to play a media file from http://localhost - you can find it in the ViewModel.cs file - you can replace this with a file of your own choosing hosted on your local PC, or you could put some content into the App package instead.

I hope you get something out of the attached project, and thanks again for your thoughts. Let me know if there's something else busted!

A penny for your thoughts on Windows Phone 7 tombstoning

Peter Torr - MSFT — Sun, 06 Mar 2011 22:06:00 GMT

One piece of feedback we hear from Windows Phone developers is that "tombstoning is hard," but there are many ways of interpreting that statement and we'd like to understand it more. We have some theories about what might be hard, but I don't want to skew any results by mentioning them here.

If you have an opinion on tombstoning in Windows Phone 7 - good or bad - please leave a comment and be as detailed as you can in the reply so we can better understand the feedback.

Thanks!

P.S. I'm joking about the penny.

This is not the exit you are looking for

Peter Torr - MSFT — Wed, 23 Feb 2011 16:15:00 GMT

[Update 7/27: fixed a typo and made it a bit clearer; thanks Nicole! Also added a link to code with the new Mango APIs]

I have previously blogged about exiting a Windows Phone application but a further post is needed due to a disturbing trend we're seeing in the marketplace: more and more applications are choosing to throw an unhandled exception in order to exit themselves.

There appear to be several reasons for this:

The application has some kind of consent screen and if the user says "No" they want to quit
The application has a complex navigation system and the only way to quit when hitting the Back key is to force-quit
The application receives an error response from a webservice and doesn't want to handle it
The application really wants an "Exit" button

The recommended way to handle #1 is covered in the previous post: just omit the "No" button and the user will figure out that pressing the Start or Back buttons both have the desired result of removinf the application from the screen.

The recommended way to handle #2 for most applications is covered in my places post (now on MSDN): when used correctly, page-based navigations will enable the user to back out naturally. For some applications that have a strong focus on "browsing" content - like the IMDb or Amazon applications, for example - the "places" concept doesn't really fit, and Yochay has published a recipe for a non-linear navigation service that should handle most cases of returning correctly to a home screen such that the Back button naturally exits your application.

The recommended way to handle #3 is to deal with the failure and let the user know something went wrong. Exceptions are meant for "exceptional" (ie, unexpected) situations, and having a web service call return an error code is not an unexpected situation. It is a terrible user experience to be interacting with an application and then suddenly see it disappear and be dumped unceremoniously at the Start menu. Obviously we don't want applications showing the HTTP error code to the user, but a simple piece of UX like "request failed; try again?" would suffice. Even if your app is totally unusable without the web service connection, you can at least show some UX along the lines of "we can't connect right now; try again later" and leave it to the user to hit Back or Start.

The recommended way to handle #4 is to embrace the Windows Phone UX and realize that an Exit button is superfluous. One explanation for why developers want to have an Exit option goes along the lines of this:

The phone has limited resources. If the user is done with my app, I want to be a good citizen and stop using resources. On other platforms (Windows Mobile, Windows Desktop, some other mobile OSes) simply switching away from an application doesn't kill it. Therefore I will let the user completely exit my app to ensure I don't use their phone's resources.

The thing is, on Windows Phone 7 the OS does take care of deactivating your application so that it can't use precious resources like CPU, memory, or battery. If the user hits Start to begin another task, your app is gone and can't possibly affect the user experience; there is no need to explicitly exit it. Furthermore, if some applications start having Exit buttons and others don't, there is a fear that customers will start to look for exit buttons everywhere. The logic goes something like this:

This app has an Exit button
I know I can just hit the power button to put the phone to sleep, or hit the Start to go to another app, so the Exit button must be there for a reason
The reason is probably that the app will drain my battery if I don't exit it (based on past experience, urban legend, etc.)
I'd better start exiting all my apps to ensure my battery doesn't drain too fast
Oh my goodness, most apps don't have Exit buttons
Panic!

We don't want to burden our users with the fear of wasting resources and the need to exit apps; we just want them to love using the phone. Putting an Exit button in your app just confuses users and reduces their overall satisfaction with the phone. That's the theory, anyway :-).

Another problem with deliberately crashing your application (vs. relying on the user to hit Start) is that the application will be removed from the back stack, breaking the user's expectation that they can return to it using the Back button. This will only get worse in the future, as users will expect recently-used applications to be in the application-switching UI (as demoed at Mobile World Congress), but applications that crash due to an unhandled exception won't appear in that list.

Certification Requirements

The Application Certification Requirements have two things to say on this topic.

Firstly, requirement 5.2.4(a) states:

Pressing the Back button from the first screen of an application must exit the application

This is most likely what drives #2 above - the app needs to pass certification testing, but due to their complex back stack the Back button doesn't actually exit the app. Ideally the requirement would add "...without resorting to throwing an exception" to make it clear this should happen naturally, but currently it doesn't. Fixing the navigation pattern will let you pass certification without throwing exceptions.

Secondly, requirement 5.1.2 states:

The application must handle exceptions raised by the .NET Framework and not terminate unexpectedly. [...] An application that terminates unexpectedly fails certification.

This requirement is enforced for normal application usage - if the application crashes randomly during testing, it will fail - but is not currently being tested for the exit case because in some ways the termination is not "unexpected" - the user pressed Back and the app disappeared. Nevertheless, this is not the spirit of the requirement and you shouldn't take advantage of it.

Requirement 5.1.2 also states:

When handling exceptions, an application must provide a user-friendly error message. You may present a message that is relevant to the context of the application. The application must continue to run and remain responsive to user input after the exception is handled.

This clearly shows that scenario #3 above (exiting when an exception is received) violates the certification requirements and should not happen.

Future Developments

The current situation isn't ideal - we have an API set that doesn't meet everyone's needs (although Yochay's sample goes a long way to solving many problems) and we have certification requirements that aren't crystal clear (or always enforced). Obviously I can't promise you anything about future updates, but we are thinking about these things and trying to improve them at all levels (APIs, certification, documentation, etc.). Your best bet is probably to wait for Mix '11 in April, but other than the keynote nothing has been announced yet so don't hold your breath for Joe Belfiore to mention exit buttons on-stage ;-).

I can now revearl that there are some new APIs in Mango to specifically deal with his - see my post on Alarms and Notifications for some sample code for dealing with "interesting" navigation scenarios.

What about XNA?

An observant developer might point out that XNA applications on the phone do have access to an Exit method, so doesn't that invalidate everything I said above? Yes and no: Yes, XNA applications can exit themselves; No, XNA applications can't not exit themselves (with apologies to Jack Donaghy). But seriously, this is more about compatibility with the other XNA platforms (Windows and Xbox) that use the Back button on a controller to show menus or exit. Additionally, the only game I have seen that actually uses this feature is Tetris; that's not to say other games don't use it, but it's clearly not used universally by XNA applications.

Feedback

Feel free to add a comment below (or send me a private mail) if you have other reasons for needing to exit your application; please be as descriptive as possible as to what your intended UX is and why you can't build that with the current API set. All feedback is helpful!

Thanks to Steve Bell and other Windows Phone folks for their input on this blog post.

How to correctly handle application deactivation and reactivation

Peter Torr - MSFT — Sat, 11 Dec 2010 20:40:38 GMT

Much has been written about tombstoning and how important it is that your application be able to save and restore state once it goes into the background. This is all good.

One of the finer points of the Windows Phone application model that has received less attention is the case where your application moves into the background and does not get tombstoned. In the current implementation of the Windows Phone operating system, there are two cases where your application will be deactivated but not tombstoned:

When calling certain launchers and choosers, the system attempts to keep your process alive in order to give a seamless Back experience for the user
If the user accidentally leaves your app (eg, via the Start or Search buttons) and immediately hits Back to return to your application

Most developers are familiar with the first case because it is a core part of application development. Many developers, however, are not familiar with the second case because it's something you don't typically encounter during normal development and testing. Let's look at the different sequence of events that happen in the tombstone case and the non-tombstone case:

Tombstone Case (typical)

Current page gets OnNavigatedFrom
Application gets Deactivated
Process dies
Process starts
Application gets constructed
Application gets Activated
Current page gets constructed
Current page gets OnNavigatedTo

Non-Tombstone Case (Start -> Back)

Current page gets OnNavigatedFrom
Application gets Deactivated
Application gets Activated
Current page gets OnNavigatedTo

See what's missing? That's right, none of your constructors get called in the non-tombstone case, because they were never removed from memory. To see this in action, try the following:

Create a default Windows Phone application in VS
Add the following line inside the App class (right after the declaration of RootFrame):

public static GeoCoordinateWatcher GCW = new GeoCoordinateWatcher();
Add the following lines inside the Deactivate handler (because you want to be a good citizen and clean-up after yourself)

if (GCW != null)
GCW.Stop();

GCW = null;

And a Button to MainPage and put the following line inside the Click handler:

App.GCW.Start();

Now run the application and click the button. Nothing should happen (which is fine).

Now hit the Start key immediately followed by the Back key, and try clicking the button again. If you are lucky, nothing will happen (same as before) but if you are unlucky the application will crash and you will be returned to the Start menu. If you are having trouble reproducing the problem, add the following line to your Deactivated handler to simulate the application doing some work during deactivation, such as saving data to IsoStore:

Thread.Sleep(2000);

By looking at the sequence of events above for the non-tombstone case, it should be obvious why the application is crashing - GCW is implicitly created in the application's static constructor (by virtue of it being a field initializer), but it is destroyed in the Deactivated event. Since the application is then re-activated without being re-constructed, GCW remains null and the call to Start() will fail.

In order to fix the problem, we simply recreate GCW in the Activated event, and now all is fine:

if (GCW == null)
GCW = new GeoCoordinateWatcher();

Another approach would be to remove the field initializer altogether, and to unconditionally construct the object in both the Launching and Activated events (possibly via a shared initialization routine). Of course performance best-practices would say to do none of this but to lazily create the object only when it is first needed, but that makes the example harder ;-). The point is that you don't have to undo everything in the activated event - you can be lazy - but you must ensure that your application can cope with being reactivated without being tombstoned. A similar sequence of events can occur for your pages, where they receive OnNavigatedFrom followed by the OnNavigatedTo without being destroyed and re-constructed in the meantime.

Note that this behaviour is covered in the existing Windows Phone documentation, but not everybody reads the docs (which is unfortunate). Please read the documentation :-)

That memory thing I promised you

Peter Torr - MSFT — Sat, 30 Oct 2010 07:32:00 GMT

Today Jeff Wilcox, David Anson, and I did a Channel 9 live session with Dan Fernandez at the PDC on Microsoft campus. You can catch it almost exactly 55 minutes into the stream here (note to self: try to remember what team you work on - it's the Application Platform team, not the Application Development team!)

One thing I mentioned was the LazyListBox, which you can find here, and the other ListBox virtualization samples that you can find on the Silverlight Performance blog here.

Anyway, I foolishly promised to publish something on my blog, so here it is. It's a simple class called MemoryDiagnosticsHelper that shows a counter similar to the built-in frame-rate counter that can be used to show how much memory you are using. It will also Assert if you go over the marketplace limit of 90MB, which is nice. It also ensures that the calls to DeviceExtendedProperties are only made in DEBUG mode so that you won't get a scary disclosure in marketplace for "identifying the device."

Anyway, the code is attached along with a very silly sample app. All you really need is the MemoryDiagnosticsHelper.cs file though, which you can pull into your existing apps and add a line like this in App.xaml.cs right under the call to EnableFrameRateCounter

MemoryDiagnosticsHelper.Start(TimeSpan.FromMilliseconds(500), true);

Procrastination FTW - LazyListBox Should Improve your Scrolling Performance and Responsiveness

Peter Torr - MSFT — Tue, 12 Oct 2010 09:14:00 GMT

Introduction

One of the things I've been working on for a while is a "smart" ListBox implementation that uses the new scrolling states and data virtualization features in Windows Phone 7 to help improve performance. Here's a relatively common pattern we see with developers who are new to Silverlight (or just new to the phone):

Get a very large dataset of complex objects, possibly coming from a web request
Bind it to a ListBox with a complex ItemTemplate that has an expensive layout, often including images
Witness an unresponsive / glitchy application during page-load or while scrolling

Sometimes Step 3 isn't as noticeable on the emulator because it is very fast on a powerful desktop computer, but on the resource-constrained phone you are more likely to see issues with performance and responsiveness when binding large, complex lists. This post includes a sample application that shows three different ways of binding to data from the Netflix OData service (which is very cool, by the way!) and how each improves on the former.

The first part of the problem (binding to a large dataset) can be mitigated by using IList instead of IEnumerable, as discussed in my data virtualization posting and in Shawn's eerily-similar post. The next part of the problem - what to do about those expensive ItemTemplates and the other heavy lifting that is required to actually show your items - is what this post is focused on mitigating. You should also read the recently-posted article on ListBox performance over at the newly-minted Silverlight for Windows Phone Performance team blog.

A Three-Step Solution

The solution outlined in this post has three parts to it, each of which I'll discuss in turn. They are:

Using the scrolling state to avoid doing work while the list is scrolling
Using different DataTemplates for your items, depending on whether they are actually on-screen or not
Using an explicit state machine for controlling the work done by items depending on whether they are visible or not

Let's look at each in turn, although they are all related.

Don't do work while the user is scrolling

The first part of the solution is to use the scroll-states exposed by the ScrollViewer in Windows Phone to detect when the list is scrolling and when it has stopped scrolling. There are two reasons for doing this. The first is that you want to avoid doing any work on the UI thread while the list is being scrolled, otherwise it won't be responsive to the user's gestures or you might see blank items in your list if the UI thread (which is creating the content for the items) can't keep up with the render thread (which is animating them). The other is that you want to avoid doing any work for items that are not visible to the user (see the next section) but the computation for what is visible and what is not visible is expensive, and per the previous sentence we don't want to do that expensive work while the list is scrolling. So we need to wait for the list to stop scrolling before we can compute the visible items.

The IsScrolling property and ScrollingStateChanged event

The LazyListBox exposes a DependencyProperty named IsScrolling that will tell you whether or not the list is scrolling; you can databind to it if you like, for example to show or hide some other UI in your application. It also exposes a ScrollingStateChanged event that you can hook to do other work when the state changes. The property and the event are synthesized by hooking the VisualStateGroup.CurrentStateChanging event of the underlying ScrollViewer, as outlined in my previous blog post on the topic. Internally, the LazyListBox also uses the scrolling start notification to alert the items in the list that they should "Pause" any work they are currently doing, and it uses the stop notification to compute the visible items in the list.

The OnListChangesComplete method

The most interesting code in the sample is probably LazyListBox.OnListChangesComplete and the functions that it calls. In particular, it uses some extension methods and some LINQ magic to check which items are visible in the list using the extension method ExtensionMethods.GetVisibleItems<T>(). This method in turn ends up calling TestVisibility for each of the virtualized items in the list (which is expensive, which is why it only happens when you stop scrolling). Basically the whole reason I need to detect list scrolling state is so that I can avoid calling OnListChangesComplete unless I know that the list changes (and animations) are, well, complete.

TestVisibility is the "expensive" work-horse, and it looks like this:

public static bool TestVisibility(this FrameworkElement item, FrameworkElement viewport, Orientation orientation, bool wantVisible)
{
// Determine the bounding box of the item relative to the viewport
GeneralTransform transform = item.TransformToVisual(viewport);
Point topLeft = transform.Transform(new Point(0, 0));
Point bottomRight = transform.Transform(new Point(item.ActualWidth, item.ActualHeight));

// Check for overlapping bounding box of the item vs. the viewport, depending on orientation
double min, max, testMin, testMax;
if (orientation == Orientation.Vertical)
{
    min = topLeft.Y;
    max = bottomRight.Y;
    testMin = 0;
    testMax = Math.Min(viewport.ActualHeight, double.IsNaN(viewport.Height) ? double.PositiveInfinity : viewport.Height);
}
else
{
    min = topLeft.X;
    max = bottomRight.X;
    testMin = 0;
    testMax = Math.Min(viewport.ActualWidth, double.IsNaN(viewport.Width) ? double.PositiveInfinity : viewport.Width);
}

bool result = wantVisible;

if (min >= testMax || max <= testMin)
result = !wantVisible;

return result;
}

In theory this method could be sped up by accumulating the maximum Y (or X) value and then assuming that each subsequent item is directly below (to the right of) the previous item, but that didn't seem worth the extra effort.

Don't compute complex layouts if the items aren't on-screen

Once we know which items are on-screen and which items are not, we can do interesting things like only show complex DataTemplates for the items the user can see. Then we don't pay the cost of databinding and laying out all the items that you can't see anyway. In the sample, I use three different DataTemplates for the LazyListBoxItem container (which are set via the LazyListBox properties):

ItemTemplate. This is the normal template that is exposed by ListBox and is used by default for all items in the list when they are not on-screen. This should be a very simple template that databinds only the bare minimum of data (if any!) and doesn't have a complex layout
LoadedItemTemplate. This is a new template that is used only when items are on-screen, and this is where you can show the full, rich UI that is databound to various properties and has a complex layout (but not too complex!)
CachedItemTemplate. This is an "advanced" template used when an item has been previously-visible but is now invisible; it is used only if your items implement ILazyDataItem (see next section)

The selection of which template to use is done in LazyListBoxItem.SetIsVisible(), which is a function that OnListChangesComplete ends up calling for all the virtualized items in the list to let them know if they are currently visible or not.

Animating data into view

Using LoadedItemTemplate along with some animations can lead to some nice effects, like the one used in the Netflix sample project. If you haven't run the project yet, the ItemTemplate looks like this:

And the LoadedItemTemplate looks like this:

The app plays a simple fade animation between the two of them when the list comes to a halt - here's the XAML, with the interesting bits highlighted (I wish copying colour-coded text from VS worked correctly... I manually formatted the code above, but XML is just too hard to format by hand):

<lazy:LazyListBox x:Name="MainListBox" Margin="0,0,-12,0" Opacity="0.3" ItemsSource="{Binding Data}">
<lazy:LazyListBox.ItemTemplate>
    <DataTemplate>
      <Border Height="100">
        <TextBlock Text="{Binding Title}" Style='{StaticResource PhoneTextLargeStyle}' Margin='112,1,12,0' Grid.Column='1' VerticalAlignment='Center' />
      </Border>
    </DataTemplate>
</lazy:LazyListBox.ItemTemplate>
<lazy:LazyListBox.LoadedItemTemplate>
    <DataTemplate>
      <Grid Height="100">
        <Grid.Triggers>
          
          <EventTrigger RoutedEvent="Grid.Loaded">
            <BeginStoryboard>
              <BeginStoryboard.Storyboard>
                <Storyboard>
                  <DoubleAnimation Storyboard.TargetName="largeText" Storyboard.TargetProperty="Opacity" From="1" To="0" Duration="0:0:0.6">
                    <DoubleAnimation.EasingFunction>
                      <PowerEase EasingMode="EaseIn" Power="3"/>
                    </DoubleAnimation.EasingFunction>
                  </DoubleAnimation>
                  <DoubleAnimation Storyboard.TargetName="details" Storyboard.TargetProperty="Opacity" From="0" To="1" Duration="0:0:0.6">
                    <DoubleAnimation.EasingFunction>
                      <PowerEase EasingMode="EaseOut" Power="3"/>
                    </DoubleAnimation.EasingFunction>
                  </DoubleAnimation>
                </Storyboard>
              </BeginStoryboard.Storyboard>
            </BeginStoryboard>
          </EventTrigger>
        </Grid.Triggers>
        <Grid.ColumnDefinitions>
          <ColumnDefinition Width="100"/>
          <ColumnDefinition Width="*"/>
        </Grid.ColumnDefinitions>
        <Image Source="{Binding ImageSource}" Grid.Column="0" Stretch="Uniform" Width="65" Height="90" VerticalAlignment="Center" HorizontalAlignment="Center" Margin="12,0"/>
        <TextBlock x:Name="largeText" Grid.Column="1" Text="{Binding Title}" Style='{StaticResource PhoneTextLargeStyle}' VerticalAlignment='Center'/>
        <StackPanel Margin="1,4,0,0" Grid.Column="1" x:Name="details" Height="80" VerticalAlignment="Top">
          <TextBlock Text="{Binding Title}" Style='{StaticResource PhoneTextNormalStyle}' Height='27'/>
          <TextBlock Text="{Binding Description}" TextWrapping="Wrap" Height="53" FontSize="{StaticResource PhoneFontSizeSmall}" Style='{StaticResource PhoneTextSubtleStyle}'/>
        </StackPanel>
      </Grid>
    </DataTemplate>
</lazy:LazyListBox.LoadedItemTemplate>
</lazy:LazyListBox>

It's pretty straight-forward stuff - the blue text is the simple ItemTemplate, the maroon stuff is the LoadedItemTemplate, and the green stuff is the (one and only) supported Trigger in Silverlight that I am using to do the fade-in animation (you could use the ControlStoryboardAction from Blend instead if you liked). Note that my ItemTemplate is very simple and consists of just a TextBlock inside a Border, whereas the LoadedItemTemplate contains a Grid with two columns, an Image, three TextBlocks, and an animation.

The net effect is that when you're scrolling the list you see the nice big title text (and nothing else), and when you stop it fades away to show you the full details including the picture. Not only does this aid with performance, but it also makes the list contents more readable as you are scrolling because the text is larger. Neat,huh?

Delay all work until the last-possible minute

The final thing we do is to not do any work at all! The system tries to avoid doing work whenever it doesn't need to, and you can also participate in this lazy behaviour if you implement the ILazyDataItem interface on your items that are added to the list.

ILazyDataItem interface

This interface is used to implement a state machine that models the various states a "heavy" object can be in. It models the data loaded into the object on two independency axes:

The speed with which the data can be retrieved (synchronous or asynchronous)
The size of the data (basically "small strings" or "large objects")

If the LazyListBoxItem class is home to one of these objects, it will use it and follow the state machine below (click to enlarge):

It looks complicated ;-) but it's actually quite simple. The common state transitions are:

Unloaded -> Minimum. You load the bare minimum content to display something on the screen (to match your ItemTemplate)
Minimum -> Loading. Time to start loading all the data for your item (to match your LoadedItemTemplate)
Loading -> Loaded. You have finished loading your items (this is a transition driven by you, not by LazyListBoxItem)
Loaded -> Cached. You were loaded, but now you're off-screen and should dump any memory-hogging data (to match your CachedItemTemplate)

There is also a Reloading state which is just a special case of Loading (when you already have some data loaded), and you can optionally support a Pause / UnPause operation to stop doing work while the list is scrolling.

In the interests of time, I did not implement ILazyDataItem in the Netflix demo (otherwise I would never have gotten this post out!) but it is used by the dummy data item in the DelayLoadListBoxItem project.

Other miscellaneous stuff

The project has some other things in it, like remembering the scroll position of a list during tombstoning (using the extension method SetVerticalScrollOffset) which turned out to be incredibly hard to get right due to the mysterious ways in which events come in, especially when databinding. It took me many, many hours of trial-and-error debugging and required a custom interface (ISupportOffsetChanges) to implement it correctly and in a way that didn't perform more work than was necessary... I really hope that it actually is a hard problem (all that work was necessary) vs. it being an obvious thing and I just wasted my time :-).

That's about it for now - hope you enjoy the code and can use it in your apps. There are several things in the ZIP file attached:

UIExtensionMethods. Implements various extension methods for dealing with the visual tree, etc.
LazyListBox. Implementation the LazyListBox and LazyListBoxItem classes, and defines the ILazyDataItem interface
DelayLoadListBoxItem. A test project that implements the ILazyDataItem interface and arbitrarily sucks up memory. More of a testing app that I used while developing the LazyListBox than anything else
NetflixBrowserTest. A test project I build after writing the LazyListBox to see the real-world difference in performance and to see how hard (or not) it would be to implement a "clean room" application that used the lazy list box.
State Machine for ILazyDataItem. A PowerPoint deck that contains the state machine image, above, for your reference

A couple of (late) links

Peter Torr - MSFT — Mon, 27 Sep 2010 07:53:09 GMT

Firstly, fellow WP7 PM Developer Dragos Manolescu is resurrecting his blog and posting about Windows Phone 7. His first WP7 post is a great introductory piece on using Location Services and Reactive LINQ on the phone (and if lambdas make your brain hurt, don't say I didn't warn you).

Secondly, the RTM Windows Phone Tools and the Silverlight for Windows Phone Toolkit were released the other week (if you didn't already know that, you're probably reading the wrong blog ;-) ).

Also, in case you weren't already aware of them, here are some other Windows Phone-related blogs you should probably follow:

Sample code from TechEd New Zealand talks

Peter Torr - MSFT — Tue, 31 Aug 2010 10:10:00 GMT

[Update September 9: Link to the recorded sessions]

[Update September 2: Updated the ZIP file to comment-out dependency on not-yet-shipped Map control :-)]

Attached to this post is a ZIP file with three projects in it:

Part1Demo, which is the demo app for WPH304 (video should be available soon at http://www.msteched.com/2010/NewZealand/WPH304)
Part2Demo, which is the demo app for WPH305 (video is available at http://www.msteched.com/2010/NewZealand/WPH305)
CloudService, which is the “backend” for the push notification section of Part2Demo

These are the latest revs of the “Building WP7 Apps in Silverlight” talks that have been given at Mix and TechEd US in the past. They should run on the current beta tools (and not long now until the RTM tools are released!). A lot of the demos use device features so you will not get the full benefit in the emulator. I will also post the “no code; all Blend” panorama apps in a separate post (they will have to wait until September 16th).

I’m not going to go into much detail in this post, since I’m tired and the apps should pretty much speak for themselves. The code is all quite simple and I have even added some comments!

One thing you will need to do is provide your own video file for Part 1 (I tried uploading mine but it was too large). It should be called "GoldCoastBeach.wmv" (guess what it was a video of!) or you can simply change the name inside the XAML file if you prefer. The only other tricky bit is in Part 2 where you will need to update the configuration of the service reference to point to your server name instead of YOUR_SERVER_NAME.

You will also need to build the CloudService project and deploy it to a web server - this project won’t open with the free VPDExpress version of VS, but it’s only needed for the push section of the demo and you can run the rest of the demos without it (you also might be able to use one of the other free Express SKUs to do ASP.NET development…)

Features shown in Part 1:

InputScope on TextBox
Drag and pinch gestures (pinch requires device or multi-touch monitor)
Accelerometer (requires device)
Microphone input (requires device)
MediaElement control
WebBrowser control
Camera capture task

Features shown in Part 2:

Navigation
Overriding the back key
Saving state during tombstoning
Push notifications (requires the CloudService project)
Location (requires device)

I hope you appreciate the effort I put into the tiles / splash screens, as well! :-)

Enjoy.

Redirecting an initial navigation

Peter Torr - MSFT — Sat, 28 Aug 2010 13:16:00 GMT

One more post on the subject of keeping screens out of the backstack. A common scenario we see is a variation of the login screen scenario I mentioned the other week. In this case, the first page the user is supposed to see depends on some state saved in by the application (maybe a user preference for which screen to see first, or maybe based on trial mode, etc.) and whilst you want that first page to be in the back stack (ie, it is a legitimate place) you don’t want any additional “landing pages” taking up a slot in the backstack. Another situation where this arises is if your application is extending the Music + Videos hub or is registered as a Photo Extension and you need to show a different page when launched from these experiences.

There are (at least) two ways of doing this; I’ll present two of them here along with a sample app that shows them in action. For my simple example, the trigger for showing a particular page is going to be whether the current time has an even or odd number of seconds (this is a silly example, but makes it easy to test both startup cases). In a real application the trigger might be based on incoming parameters, settings stored in IsoStore, etc.

Cancelling Navigation

The first way to change your initial page is to cancel the incoming navigation to MainPage.xaml and then fire off the desired navigation instead. This is easily done in a few lines of code; firstly, at the end of the App constructor we add an event handler to the Navigating event:

RootFrame.Navigating += new NavigatingCancelEventHandler(RootFrame_Navigating);

In the event handler, we do several things. First, we check if the navigation is to MainPage.xaml (the NavigationPage specified in the WMAppManifest.xml file) and if not, we bail:

// Only care about MainPage
if (e.Uri.ToString().Contains("/MainPage.xaml") != true)
return;

Next we perform a simple check to see which page to load (in this case, are the seconds odd or even?), but this is where you’d do your own logic for switching pages:

// Our dummy check -- does the current time have an odd or even number of seconds?
DateTime time = DateTime.Now;
int seconds = time.Second;
bool isOdd = (seconds % 2) == 1;

Finally we kick off a navigation to the desired page, being careful to avoid overlapping navigations (which will fail):

// Cancel current navigation and schedule the real navigation for the next tick
// (we can't navigate immediately as that will fail; no overlapping navigations
// are allowed)
e.Cancel = true;
RootFrame.Dispatcher.BeginInvoke(delegate
{
    if (isOdd)
      RootFrame.Navigate(new Uri("/odd.xaml?method=cancel%20navigation&time=" + time.ToLongTimeString(), UriKind.Relative));
    else
      RootFrame.Navigate(new Uri("/even.xaml?method=cancel%20navigation&time=" + time.ToLongTimeString(), UriKind.Relative));
});

Using UriMapper

The second method you can use is based on the UriMapper class, which is a standard part of the Silverlight 3 navigation framework. UriMapper was slightly easier to use in the Mix-era CTP when we set the RootVisual of the application to a frame inside of App.xaml, but it’s still easy to do with the new delayed approach. First of all we add a new UriMapper to the Resources section of App.xaml:

<!--Simple UriMapper that will be programmatically updated to point to the right page at runtime—>
<UriMapper:UriMapper x:Name="mapper">
<UriMapper:UriMapping Uri="/MainPage.xaml" />
</UriMapper:UriMapper>

Then instead of handling the Navigating event (as before), we simply attach the UriMapper to the RootFrame …

// Get the UriMapper from the app.xaml resources, and assign it to the root frame
UriMapper mapper = Resources["mapper"] as UriMapper;
RootFrame.UriMapper = mapper;

and re-write the rule for MainPage based on the desired page:

// Update the mapper as appropriate
if (isOdd)
mapper.UriMappings[0].MappedUri = new Uri("/odd.xaml?method=UriMapper&time=" + time.ToLongTimeString(), UriKind.Relative);
else
mapper.UriMappings[0].MappedUri = new Uri("/even.xaml?method=UriMapper&time=" + time.ToLongTimeString(), UriKind.Relative);

As you can see, the code is mostly the same, the difference is whether it is an explicit cancel-then-navigate or whether it is a simple URL-rewrite that happens. If you don’t know which one to use, I would recommend the UriMapper solution first (because you can easily extend it for other, non-dynamically-re-mapped scenarios) but it does require that you know what the final URI should be in a synchronous fashion. If for whatever reason you need to perform an asynchronous operation to determine which page to load – or if you just prefer a 100% code solution – you can use the “cancel navigation” approach. Just be sure to navigate within 10 seconds (or include a splash screen) or the system will terminate you for being unresponsive.

The attached sample lets you pick which approach you want to try by modifying the static USE_CANCEL_NAVIGATION flag set at the top of App.xaml.cs.

Introducing the concept of “Places”

Peter Torr - MSFT — Sat, 28 Aug 2010 10:53:00 GMT

TechEd Australia is all wrapped up, and I wanted to let everyone else know about one of the new concepts we’re introducing around application structure. As we’ve previously discussed, Windows Phone 7 applications are composed of pages that exist on a back stack and can be accessed by the user with the hardware Back key.

What we haven’t been so clear on is exactly which parts of an application should be a page and which parts shouldn’t be a page, and lots of folks both internally and externally have been bumping into issues around login screens, infinitely-growing back stacks, and so on. The good news is that we finally have some guidance to share around these issues that should help you to build apps that fit in with the navigation-based user model and still meet all your functional requirements. Not to worry though – this isn’t something entirely new. It’s just a refinement on the page-based model we’ve been talking about all along, but takes into account transient UI, content browsing, and other scenarios. We’ve also tweaked the 1^st-party apps to follow this model, whereas in the past there were some inconsistencies there, too.

The basic premise is that the phone (and hence the applications on it) consist of a set of “places.” A place is a “user-recognizable collection of persistent state” (thanks to Alan Bush for that succinct description!) or in layman’s terms it’s a screen that the user visits that contains information, content, or links to other places. Now since a picture is worth a thousand words, let’s take a look at the structure of a typical content-browsing application (click to enlarge):

(I apologise for the muted tone of that image; the Tech-Ed organisers like to use a very bland palette in the slide templates!)

What the picture is showing is a simple app that consists of a Home Screen, an All Widgets list, a Details View for Widgets (which consists of several pivots), a Details View for Gadgets, a Search screen and a Settings screen. The application also has a Splash Screen and a Login screen. The arrows represent transitions between screens, with the special case for Login that several of the screens can show the login screen depending on various situations (returning from tombstoning, cookies timing out, etc.). Note that both the Widgets details page and the Gadget details page have little circular arrows on them, meaning you can transition from one Widget (or Gadget) to another without going to a new screen – this is very much like the way Outlook on the desktop lets you switch to the Previous or Next mail inside the same item window by clicking on the little blue arrows:

(Those lucky folks with Windows Phone 7 prototype devices will recognize this same behaviour in Outlook on the phone, too). This is also how a typical photo viewing application works – once you have drilled down into the album and then into an individual photo, you typically switch to different photos in-place by swiping left or right (or clicking previous / next arrows on the desktop).

You’ll notice that I was very careful to use the word “transition” rather than “navigate” in the description above, because not all the arrows represent navigations – only transitions between different places are navigations. The following transitions don’t represent navigations because they do not switch to different places (and because they’re not navigations, they’re not on the backstack and aren’t automatically reversed by the back key):

The transition from the Splash Screen to the Home Page, since the Splash Screen is not a place
The multiple transitions to the Login screen, since the Login Screen is not a place
The transition from the Widget Details back to itself, because it re-uses the same place
The transition from the Gadget Details back to itself, because it re-uses the same place

So hang on – how did we determine that the Splash Screen and the Login Screen are not places? Well, let’s look at the definition again: a user recognizable collection of persistent state. The splash screen clearly doesn’t contain any state – it’s just smoke and mirrors to make the app launch seem faster than it really is – and the login screen doesn’t really contain any state either; it simply asks you for credentials. The “user recognizable” bit can also help you determine if other parts of your UI should be places or not by asking a couple of simple questions: Would the user explicitly want to visit this screen? Would the user remember they were on this screen, and want to return to it? The splash screen and login screen both fail these tests too; you don’t really want to see either of these screens (they just appear at the appropriate time) and once you’re in the app you don’t particularly remember seeing them or want to return to them. They’re speed bumps that get in the way of the actual content that the user really cares about.

Yet another way to think of it: if you were building a web site and could provide a deep link to a particular screen, would you bother to do so? Again the splash screen and the login screen both fail that test, except of course for those sites that want to force you through an intro movie. (I just wasted about half an hour trying to find the old “skip intro” website – you know, the one that had an endless intro movie that made fun of Flash intros – but couldn’t find it… bonus points to anyone who can link to it in the comments!)

So what to do about these non-place screens and these non-navigational transitions? Well, the splash screen is an easy case because we take care of it for you. It’s never on the backstack so the user can never return to it. As for things like the login screen or other transient UI, the Silverlight Popup control is a great solution for showing content that (partially) covers the screen without doing a full navigation. And of course you can hook up the BackKeyPress event and set e.Cancel to true while the login screen / popup dialog / etc. is visible to enable the familiar “back closes dialogs” behaviour without worrying about navigation.

For places that are used to view multiple pieces of content (Widgets and Gadgets in this case), you can transition between them easily enough without navigating by simply re-binding the controls on your page to a new DataContext, or by loading multiple instances of a UserControl inside of the page, or by any other mechanism that you might like to use for showing new content inside a single page. The mechanism through which the user transitions forwards and backwards through the items is up to you – for example, using “previous” and “next” AppBar buttons – but whatever you do please don’t abuse the Back key for local transitions!

One question that is left up to the reader is whether to save a local history of transitions that occur in a given place so that if the application is tombstoned the user can retrace their steps. I say “local history” because these aren’t navigations and aren’t on the backstack and hence aren’t managed by the normal backstack (and I repeat: whatever you do, don’t override the Back key to unwind the local history of a given place!). For some things, like simple previous / next browsing (e-mails, photos, search results, etc.) all you need to save in your page State is the current index, which along with your NavigationContext should provide all the information you need to traverse the dataset when returning from a tombstoned state. For applications that have a more complex local transition history, such as free-form browsing of linked items (think: Amazon- or IMDB- style application), you may choose to store some of that history in page state but you will probably want to put a reasonable limit on the number of items you store. The key point is that if the user hits the hardware Back key they return to the previous place (eg, category screen, search results list, etc.) and not to the previously-viewed item.

Here’s a handy guide you can use to help figure out what common parts of an application are places and which are not:

Type of screen	Place?	Notes
Splash screen	No	Transient part of the startup experience; user cannot navigate to it
Panorama	Yes	A common “home screen” approach for Windows Phone applications
Details page	Yes	Very common for data-centric apps, parameterised via the query string
Pivot item	No	A pivot item is a smaller part of the larger pivot page, which is the place of interest
Login dialog or Error dialog	No	Transient UI triggered by application state; user does not navigate to it directly
Item enumeration	No	Browsing similar content is an “in-place” activity, not a navigation

And a quick summary of how to deal with various types of screens:

Screen type	Implementation	Back key behaviour	Tombstone behaviour
Place	PhoneApplicationPage	Automatically goes back or exits the application Don’t override except in the case of data loss	Automatically remains on backstack
Transient UI	Popup, ChildWindow, etc.	Application should override to cancel the popup SIP and MessageBox automatically cancel themselves on back	Application should dismiss / cancel popup during navigation
Item Enumeration	UserControl etc.	N/A; hosted inside of parent page	Application should save active item as appropriate

Crazy Coincidental Coding, Batman!

Peter Torr - MSFT — Tue, 17 Aug 2010 23:17:54 GMT

My Silverlight cohort and all-round good guy Shawn Oster posted on exactly the same topic that I did at almost exactly the same time... and we didn't co-ordinate it at all!

http://shawnoster.com/blog/post/Improving-ListBox-Performance-in-Silverlight-for-Windows-Phone-7-Data-Virtualization.aspx

Creepy, huh?

Shawn goes into more detail and calls out one of the key requirements for virtualization, which is that you must have a custom DataTemplate in order for virtualization to kick in.

Virtualizing Data in Windows Phone 7 Silverlight Applications

Peter Torr - MSFT — Tue, 17 Aug 2010 06:38:00 GMT

One of the cool features of lists in Silverlight is that they can "virtualize" the UI objects needed to render the list, reducing the amount of memory and CPU necessary to load large lists. For example, if you bind a ListBox to 1,000 items in Silverlight, it will only create ListBoxItems for the first few screens' worth of data (say, 30 objects) and create the UI for those based on the DataTemplate. The other 970 items do not get UI objects generated for them, which is a great saving of resources. As you scroll through the list, Silverlight recycles these container items and binds them against the rest of the data, giving the illusion that all the items are in the list at once.

One of the limitations of this in desktop Silverlight is that although the UI is virtualized, the data is not -- so although that 1,000 item list only has a fraction of the UI elements created, it needs all 1,000 of the data objects created and loaded, which can be a resource issue (long load times / high memory usage). This is because in desktop Silverlight the ListBox and other controls databind to IEnumerables, where the only option the control has is to enumerate the entire list to find out how large it is.

Enter Silverlight for Windows Phone, where we are more resource constrained than the desktop and can't afford to create all those data items like the desktop can. A simple solution is available for this, called data virtualization. The trigger for this is using an object that implementes IList (instead of just IEnumerable) as your ItemsSource. Using this more flexible interface, Silverlight can simply query the list's Count to find out how large it is and can request the individual items it needs to fill the virtualized UI objects via the indexer. This approach enables databounds lists in Windows Phone 7 to be essentially unlimited in size; the sample attached to this post is a list of 1,000,000 objects (yes, <Dr. Evil voice>one million objects!</Dr. Evil voice>) that binds incredibly quickly, jumps to any point incredibly quickly, and scrolls like a champ. Try doing that on the desktop!

The sample also shows using a (very, very dumb) cache for storing even more objects than Silverlight virtualizes, in case you want to speed up certain operations. In this example, the cache is a dumb MRU cache that really only works for scrolling back through the list (if you scroll from 0 - 50 and then scroll back down to 0, a lot of the items will be returned as "cached items"). I don't recommend you actually use this cache, because it is dumb and slow, but you can see how the technique could be used to provide smart caching, or even predictive pre-loading of items, etc. to best balance memory usage and performance.

The only IList members you need to implement are:

Count, to return the actual number of items in your list;
IndexOf, to return the index of a specified item if it is in the list; and
this[], to return the item at a given location (implementing set is not required)

Everything else can simply throw NotImplementedException, although of course it is nice to implement the other members if you play to use your data list in any context other than databinding.

Homeward Bound...

Peter Torr - MSFT — Tue, 17 Aug 2010 05:14:29 GMT

Well, well, well. There I was sitting in my office when I get an e-mail asking if I wanted to present Windows Phone 7 developer content at Tech.Ed Australia and Tech.Ed New Zealand... what did they think I'd say - "No"?!? :-)

Suffice it to say I'll be at both conferences, and spending some time in Sydney and Melbourne as well so if you're going to be at the conference maybe I'll see you there. I will be presenting the same kind of content that was already given at Mix 10 and Tech.Ed US, but it will be updated with the latest information on navigation, controls, and so on.

Updated Tilt Effect

Peter Torr - MSFT — Wed, 11 Aug 2010 08:15:00 GMT

Jeff has posted a version of the Windows Phone 7 “tilt” effect that is packaged as a control, built by Luke. It’s only fair that I update my tilt code too – it uses the same attached property implementation as my previous tilt code, but the new updated tilt algorithm (direct from the shell team) that is used in Luke’s control.

This version uses a global camera effect to ensure that each object tilts not only around its own centre, but is also angled towards the middle of the screen. This effect is accomplished by first translating the object to the middle of the screen doing a normal RenderTransform (in 2D space), and then transforming it back where it came from using a Projection (in 3D space):

TranslateTransform transform = new TranslateTransform();
transform.X = centerDelta.X;
transform.Y = centerDelta.Y;
element.RenderTransform = transform;

PlaneProjection projection = new PlaneProjection();
projection.GlobalOffsetX = -1 * centerDelta.X;
projection.GlobalOffsetY = -1 * centerDelta.Y;
element.Projection = projection;

This is a relatively simple trick that is used in several other places in the Windows Phone 7 animations, something I hope to be posting more on later.

Other than the global camera, a switch to using manipulation events, and some general code clean-up, the basic technique has not changed from the previous version:

An attached property, TiltEffect.IsTiltEnabled, can be placed on any element in the tree (typically the root of a page or even the frame)
When this is done, the control starts listening for ManipulationStarted events on that element
If a manipulation is detected, the code checks the object being manipulated to check whether it is a "tiltable" object
If it is, the appropriate RenderTransform and Projection are added to the element, and the ManipulationDelta and ManipulationCompleted events are hooked
Whenever your finger (mouse) moves, the tilt angle is updated
When the manipulation completes (or when you leave the hit-area of the control) an animation is run to "spring" the control back into place after a short delay

This is all done in a pretty efficient way, such that there is only ever one animation in the app and so that the added transforms and projections are removed after use. Attached is a simple example project that uses the updated effect along with some super-ugly demo pages that show the effect in, errr, effect. It also behaves nicely with tombstoning so that it remembers the scroll positions of each page and the settings you have chosen on the first page. Fingers crossed, this will also make it into the official documentation as a sample such that even developers who don't read my blog will have access to the tilt effect in their apps (although shame on them for not reading! ;-) ).

Jeff’s improved ProgressBar template

Peter Torr - MSFT — Mon, 02 Aug 2010 20:57:32 GMT

Another quick post... Jeff Wilcox has posted an improved template for the Indeterminate ProgressBar for Windows Phone. He goes into a little of the history behind this, too. I recommend you use his updated control if you are showing an indeterminate progress bar and seeing sluggish performance.

http://www.jeff.wilcox.name/2010/08/performanceprogressbar/