1. Step: define a custom attached property on Image that takes the URI to your image.

2. Step: implement the download piece when the property changes and customize the header as needed.

3. Step: Now use your brand new property in your app's XAML.

Full sample project is attached.

ImageWithCustomReferer.zip

Tip 1: Circular Navigation

Consider the following sequence in the demo app: Log in (empty user/pwd) -> Send a Message -> type something -> hit 'Home' button (in the App Bar) -> Get Stock Quotes -> hit 'Home' button -> Send a Message.  While you do this, please monitor the helper control on the top right, which shows you the current navigation backstack. The result will look like this:

There are two small problems here that will likely confuse the user: (a) the user didn't get back to the message they were typing and (b) the user is deeper in the navigation stack than likely intended. To solve this and avoid confusion, you have two options (I chose option A for my demo):

Solution A: Avoid Circulation Navigation altogether. In this case, just get rid of the 'Home' App Bar Buttons and the user will be just fine using standard means of navigation.
Solution B: Instead of navigating forward to 'Home', walk the backstack programmatically, until you reach the Start Page. More details in this white paper by Yochay Kiriaty.

Tip 2: Dealing with transient Pages on the Backstack

If you now hit the back button a couple of times from the current state of the app, you will notice two issues: (a) we get back to the LoginPage and (b) we can't exit the app as the back key seems to get stuck. The latter is big no-no and will cause your app to fail certification. It's an easy fix though as the app was just marking the back key as handled for no valid reason, so removing the highlighted line will fix this:

protected override void OnBackKeyPress(System.ComponentModel.CancelEventArgs e)
{
    e.Cancel = true;
    base.OnBackKeyPress(e);
}

But how do we fix the root problem of hitting the LoginPage on our way back and exit the app cleanly? Again there are a few options to fix this. My personal preference is the following: I consider the LoginPage semantically not really a page that participates in navigation, but rather a control that overlays the StartPage and is shown only if the StartPage is navigated to without an existing user context. To implement this, I just move LoginPage code into a control (LoginControl) and include that in the StartPage. The StartPage now can control the visiblity of the LoginControl programatically as needed.

For completeness sake, alternate methods for solving the problem of dealing with transient pages on the backstack include cancelling the navigation or using UriMapper. Peter Torr has a blog post covering both.

Tip 3: Saving Page state on Tombstoning

Consider the following scenario in the demo app:  We navigate to the "Send a Message" page and start typing a message. Now we want to find some data on the Internet and use copy & paste to include it in the message. For that we hit the Search button in the App Bar, do our search and then navigate back. The result is very frustrating: the message that we had typed tediously is now gone. Why is that, what happened here? Tombstone happened!

The short story is this: when the user navigates forward, away from your app, then your app will receive an entry on the global backstack, get a chance to save its state and then the process will be shut down. The longer story is documented here. So the problem in the demo app was that we didn't save our state before we got Tombstoned. The general recommendation for saving your Page's state is to persist it in OnNavigatedFrom() and restore it in OnNavigatedTo(), in MessagePage.xaml.cs:

protected override voidOnNavigatedFrom(NavigationEventArgs e)

{

    base.OnNavigatedFrom(e);

    if (App.CurrentNavigationMode != NavigationMode.Back)

    {

        this.State["message"] = tbMsgBody.Text;

    }

}

protected override voidOnNavigatedTo(NavigationEventArgs e)

{

    base.OnNavigatedTo(e);

    if (this.State.ContainsKey("message"))

    {

        tbMsgBody.Text = this.State["message"] as string;

    }

}

I want to point out one small optimization I have made here in the OnNavigatedFrom() call:  I will not save the state if my navigation goes backwards. This is because when going backwards, the current page (and its state) drops off the backstack. There is no way the user could ever come back to that page instance, so there is no need really to persist that state. In this app it doesn't buy us much performance gain, but on pages that save large amounts of data, you can save precious CPU and battery with this optimization. Unfortunately, it's not completely straight forward to figure out the navigation mode, so I had to build a little static helper property. It's something we want to improve in the next version.

Tip 4:  Saving Application state on Tombstoning

Since the state is being saved on a per page basis, it is important to perform Tombstone tests for each page in our app. So let's start a fresh instance of our app and test the Stock Quote Page:  After the quotes are downloaded, hit the Windows button to navigate forward (which will Tombstone our app). Now watch what happens when we come back to our app: Without debugger you will just see a little flicker and then you are back at the start screen. With debugger attached you will see that we are crashing in the constructor of the StockPage class.

public StockPage()

{

    InitializeComponent();

    tbCurrentUser.Text = "CurrentUser: " + App.CurrentUser.Name;

    this.Loaded += new RoutedEventHandler(StockPage_Loaded);

}

The reason for this is fairly simple: the constructor assumes that the static Application property for the user context is always set (since it's set during Login), however this won't be true when returning from Tombstone, if we don't preserve the application state correctly. The general recommendation for saving global app state is to do this in the Deactivated event and then restore it in the Activated event. The latter was missing in the demo app, hence the crash. So now we are adding the highlighted line to fix this problem (in App.xaml.cs):

private void Application_Activated(object sender, ActivatedEventArgs e)

{

    App.CurrentUser = PhoneApplicationService.Current.State["userContext"] as UserContext;

}

private void Application_Deactivated(object sender, DeactivatedEventArgs e)

{

    PhoneApplicationService.Current.State["userContext"] = App.CurrentUser;

}

With these four tips/fixes, our app is now much more robust and consistent from a navigation perspective compared to where we started. There are still some other problems in the app, related to the various different phones states though. This will be the topic of my next blog post.

NavigationTips.zip

I had a great time at MIX and I am very excited about the new Windows Phone Mango features we announced as well as all the cool stuff that is coming in Silverlight 5. Watch the Day 2 Keynote for some great demos around the new features. The Silverlight 5 Beta is available for download now here, the Windows Phone Mango Tools/Emulator will become available a little later next month.

This weekend I will work on some follow-up posts to my MIX session and get the demo/samples uploaded here. Stay tuned ...  :-)

Update (4/20): attaching my slide deck

04.swick.tips.03292011.psf.pptx

JPG vs. PNG

If you can make a choice between using JPG and PNG, choose JPG for all your opaque images. The JPG decoder in the Windows Phone 7 operating system is considerably faster than the PNG decoder. If you need to use images that have transparency, PNG is your only choice though.

Resource vs. Content

Images (or any files for that matter) that are part of your Windows Phone XAP can have their "Build Type" set to either "Resource" or "Content" in Visual Studio. At first sight it doesn't seem to make any difference what you choose here, as in both cases your files end up getting packaged up in the XAP. The difference becomes visible when you crack open your XAP (rename it to .zip and unzip it): now you can see all your files of type "Content", but you won't find the files of type "Resource" because those are embedded in the assemblies (.dll files). OK, why do I care? You care because the larger your application's DLL, the slower your app will launch. On the other hand, once they are loaded the images will show up quicker compared to having them load from disk later. Summary: include your images as "Content" to optimize for quick start up, include them as "Resource" to optimize for quick access.

The other thing to note as that there is a difference in URI syntax for images included as "Content" vs. "Resource". Check out the attached sample and navigate to the "Content vs. Resource" page for more details on this.

Content: <Image Source="/ImagesAsContent/smiley1.png"/> 

Resource: <Image Source="..\ImagesAsResource\smiley3.png"/> 

Async vs. Sync Loading of images

If you drill a little deeper into the Imaging APIs you will come across the BitmapImage class, which is doing most of the work behind the scenes when you create an Image. It can load things in two different modes:

  BitmapImage.UriSource = uriSource; // loads the image via URI, asynchronously
  BitmapImage.SetSource(stream);     // loads the image from stream, synchronously

Note that loading the image asynchronously doesn't mean it will happen completely off-thread. This is because currently the image decode is happening on the UI thread. For some more information about asynchronous loading of images while keeping the UI thread responsive check out this blog post by David Anson.

Some more trivia about async vs. sync loading:

• If you load an invalid image file synchronously, you will get an exception
• If you load an invalid image file asynchronously, the ImageFailed event fires (if you are subscribed)
• If you load an valid image file asynchronously, the ImageOpened event fires when it's done loading
• If you load an valid image file synchronously, the ImageOpened event does not fire

To these differences in action check out the attached sample and navigate to the "Loading" page:

Image Caching

This is an important one, and MSDN is currently fairly silent about it. If you were ever wondering why your image memory didn't get released after clearing the Source and removing the Image from the tree, you were most likely seeing Image caching in action. This is an intended performance optimization, to avoid (down)loading and decoding the same image over and over again. Instead we keep a cache in memory that we can easily and quickly reuse. This is not to confuse with the browser cache for downloaded files.

While this is a nice and free performance optimization, at times it can blow your memory  unnecessarily, especially when you cycle through many images that you will never come back to. Their cache will use up memory for the lifetime of your app. The good news is that you can delete the cache when you decided that you no longer need it:

  BitmapImage bitmapImage = image.Source as BitmapImage;

  bitmapImage.UriSource = null;

  image.Source = null;

Being smart about this can save you quite a bit of memory usage, which is a precious resource on a phone device. In the sample app, go to the "Caching" page and monitor the memory usage as you show/clear the image. Then check the box and try again. You will see a difference of ~3MB in the example case.

BitmapCreateOptions

This is a quick, yet interesting one. If you create BitmapImage objects by hand, you might wonder why it doesn't report the size of the image after you think it's done creating the image. This is because by default the CreateOptions property is set to "DelayCreation", which means that the object really gets created only when it's indeed needed, meaning the BitmapImage is assigned as the source of an Image element or an ImageBrush that are in the live tree. This allows creating collections of BitmapImages up front on start up, without having to pay all the cost (CPU & memory) until the app actually needs the respective images. If you want to force immediate creation, set the CreateOptions to "None". There is another option (IgnoreImageCache) that isn't terribly useful for many practical purposes, but it's needed by the design tools (e.g. Blend).

In the sample app, if you go to the "CreateOptions" page, go through the Create/Show/Clear sequence once with CreateOptions=DelayCreation and once with CreateOptions=None and monitor the Size value to see the difference in action.

Custom Decoding

By default the Imaging APIs will decode images in their natural resolution (except when auto-downsampling, more about that later). However, in many cases this is more than you actually need on a phone display. If you are downloading a collection of 320x320 images from a service only to display them as 32x32 thumbnails, you would be wasting a lot of memory if you decode them at their natural resolution.

On Windows Phone (specifically, not on desktop) the platform provides the PictureDecoder API that allows to specify the resolution you want to decode to:

  image.Source = PictureDecoder.DecodeJpeg(jpgStream, 192, 256);

Note: in the current release there is an unfortunate bug in this API as the values for width and height are swapped. To workaround it just pass your width into the height parameter and vice-versa. This will be future compatible, as we will fix this with a quirks mode for existing apps.

To see the memory gains from doing this, open the sample app and navigate to the "Custom Decoding" page. Switch between the two resolutions and monitor the memory usage.

Auto Downsampling

This is the last piece of need-to-know trivia when dealing with images in Silverlight for Windows Phone 7. The background is that individual elements are limited to 2048x2048 size on Windows Phone 7. Anything beyond that will be clipped. This means that if you want to consume an image that is larger than 2048 pixels in either dimension, it will not show correctly/completely. To avoid this potential confusion, the platform automatically downsamples large images so that they fit into 2048x2048. This is different from desktop Silverlight where this limitation does not exist.

In the sample app I am consuming an image of size 3000x2102, which subsequently gets downsamples to 1500x1051.

Phew, this post was longer than I thought it would be. Turns out there are a lot of little things to learn about Images in Silverlight for Windows Phone 7. Thanks for reading this far and I hope you found this post and the attached sample app helpful.

ImageTips.zip

Stay tuned for more.

Cheers, Stefan Wick

With Silverlight 4, we introduced an exciting new capability for Out-Of-Browser apps: Trusted Applications - one of the key new fatures of Trusted Applications is the ability to integrate with COM Automation interfaces on your Windows PC. What does this mean? This allows you to call into native components on your system that are either provided by the OS or installed by the user or system admin. On MSDN you can find some sample code for the canonical example that highlights the power of this feature: integrating Microsoft Office features into your Silverlight application.

In this blog post, however, I want to show some other cool things you can do with these new APIs on your PC: I want to use the systems handwriting recognizer as well as the systems speech synthesizer within my Silverlight application. Let's do the easy part first and take a look at how we get the speech synthesis done (in the attached sample, this plays back the recognized handwriting):

In line 3 we create an instance of the SAPI.SpVoice (SAPI = Microsoft Speach API). Now we can just call the Speak() method (line 4) in order to have the desired text spoken by the machine. Make sure you turn on your speakers.

For the handwriting recognition part, the code looks a little bit more complicated, mostly for two reasons: The COM Automation API for Ink has some oddities & we need to convert the users strokes from pixel space into HiMetric. Here is the full code needed to implement this as extension method on Inkpresenter to have its writing recognized by the system's handwriting recognizer:

If you are a little lost, that's OK. Here is how/why it works: :-)

On line 1 we just define the conversion factor for pixels to HiMetric (the coordinate space used by the native handwriting recognizer on the Windows system). Lines 4-6 are all about getting us a new RecognizerContext, which is the primary interface for the native recognition engines. In lines 6-7 I am using a little trick to get a new empty Ink object. There is no Automation-compliany way to produce one, but I can create an InkCollector that owns an Ink object. Then I can steal it for my purpose. All of lines 10-19 are about converting the Silverlight Stroke data (from pixels) into native Stroke data (in HiMetric). Last but not least, in lines 21-23 we pass the Strokes down to the recognizer have have them recognized synchronously.

The full source code for the sample is attached to this post. When you run it, please be sure to run it as Out-Of-Browser app, because Trusted Application features aren't supported in the browser in Silverlight 4.

Enjoy! :-)

HandwritingRecognitionDemo.zip

The first new feature I want to show is Perspective 3D transformation. We have added a powerful new property 'Projection' to UIElement that lets you rotate and move any element in your tree in 3D space! The usage is very simple, no complicated math required - just set the Projection property to a PlaneProjection in XAML or code and specify how you want to rotate or move your elements. You can then change these properties dynamically at runtime, either through code or animations.

<Grid >

  <Grid.Projection>

    <PlaneProjection RotationX="20" RotationY="30" RotationZ="-10"/>

  </Grid.Projection>

</Grid>

(More info on Perspective 3D in Silverlight 3 Beta)

Below is a live example of this new feature in action. The source is attached to this post. Note that you need the Silverlight 3 Beta Tools for VS in order to build the project. To view the live sample on this page you just need the Silverlight 3 Beta runtime installed. In the sample I have two surfaces back-to-back to each other, simulating a postcard in 3D space. Use the sliders to rotate the postcard around x, y or z axis. To demonstrate that the projected visuals are actually live and also take input, I have ink-enabled then, so you can draw on either side of the postcard.

The below sample has been update for the Silverlight 3 RTW Runtime (download)

InkPostcard.zip

SilverlightApplication39.zip

Creating ink strokes with a customized appearance is fairly straight forward with Silverlight 2. You basically collect StylusPoints in mouse events as usual, but instead of adding them to stroke objects, you just draw your own geometries or shapes at the stylus/mouse location.

When collecting sample points during the MouseMove event, please be sure to call the StylusDevice.GetStylusPoints() method and process all points returned from that call. This will ensure that stylus users will get the full fidelity of input points, since their pointing device reports points more often than the MouseMove events fires. Also it is good practice to interpolate points between sample points, since they won't usually be equidistant.

I have a attached a sample project that demonstrates the concept end-to-end using Ellipse shapes with a LinearGradientBrush to give my ink strokes a custom look. Below is live version of the sample for you to play with.

CustomInkRendering.zip

The key that enables this scenario is the StylusDevice.Inverted property. It reports during mouse events whether the front-of-pen (stylus) or back-of-pen (eraser) is being used. The app can then switch into inking or erasing mode automatically, according to this value.

Here is the code-behind you need to add for an InkPresenter to enable this scenario:

public partial class Page : UserControl

{

    public Page()

    {

        InitializeComponent();

    }

    private void inkPresenter_MouseLeftButtonDown(object sender,
                                                  MouseButtonEventArgs e)

    {

        inkPresenter.CaptureMouse();

        if (e.StylusDevice.Inverted == false)

        {

            // ink mode

            newStroke =

               new Stroke(e.StylusDevice.GetStylusPoints(inkPresenter));

            inkPresenter.Strokes.Add(newStroke);

        }

        else

        {

            // erase mode

            erasePoints = e.StylusDevice.GetStylusPoints(inkPresenter);

        }

    }

    private void inkPresenter_MouseMove(object sender, MouseEventArgs e)

    {

        if (e.StylusDevice.Inverted == false)

        {

            // ink mode

            if (newStroke != null)

            {

                newStroke.StylusPoints.Add(

                    e.StylusDevice.GetStylusPoints(inkPresenter));

            }

        }

        else if (e.StylusDevice.Inverted == true)

        {

            // erase mode

            if (erasePoints != null)

            {

                erasePoints.Add(
                   e.StylusDevice.GetStylusPoints(inkPresenter));

                StrokeCollection hitStrokes =
                   inkPresenter.Strokes.HitTest(erasePoints);

                foreach (Stroke hitStroke in hitStrokes)

                {

                    inkPresenter.Strokes.Remove(hitStroke);

                }

            }

        }

    }

    private void inkPresenter_MouseLeftButtonUp(object sender,
                                                MouseButtonEventArgs e)

    {

        inkPresenter.ReleaseMouseCapture();

        erasePoints = null;

        newStroke = null;

    }

    private StylusPointCollection erasePoints = null;

    private Stroke newStroke = null;

}