Jeff Wilcox » Silverlight

Exploring List capacities and growth on the Windows Phone

Jeff Wilcox — Wed, 18 Aug 2010 01:33:15 +0000

Since the generic .NET list (List documentation) is a pretty common data structure found in phone apps, I figured it was worth a few minutes to direct everyone’s attention to how the list and its capacity works on the phone.

Unlike desktop computers, where we’re often dealing with gigabytes of potential memory on a modern operating system, the phone has a number of fun and unique memory challenges that managed code developers should be cognizant of.

If you’re using the generic lists in your Windows Phone application, it’s OK to have a bunch sitting around – their default capacity is actually zero until you add items, but you can alter this behavior.

Constructed capacity is ZERO

When you create a new List, the constructed capacity is 0. This means that the cost of creating a new list of pretty minimal, and creating one does not typically allocate any memory for items.

List myList = new List();
// myList.Capacity == 0

I’ve heard of developers who used to think that at construction the list had a large capacity, and that setting an initial size to a few digit number was a performance win. This is often not the case.

First item brings the capacity to 4 items

The first time that you add a single item (or a few), you’ll notice that the capacity size on the Windows Phone will be 4. This is because the internal default number of 4.

List myList = new List();
// myList.Capacity == 0

myList.Add("hello");
// myList.Capacity == 4

You can add 4 items and the capacity will remain at 4.

List myList = new List();
// myList.Capacity == 0

myList.Add("hello");
// myList.Capacity == 4

myList.Add("world!");
// myList.Capacity == 4

myList.Add("bonjour");
// myList.Capacity == 4

myList.Add("le monde!");
// myList.Capacity == 4

Capacity + 1 grows the capacity exponentially

Once the Count == Capacity, it will exponentially grow the capacity. So the capacity will move from 4 to 8 to 16 to 32, 64, 128, 256, … 1024, and so on.

List myList = new List();
// myList.Capacity == 0

myList.Add("hello");
// myList.Capacity == 4

myList.Add("world!");
// myList.Capacity == 4

myList.Add("bonjour");
// myList.Capacity == 4

myList.Add("le monde!");
// myList.Capacity == 4

myList.Add("a fifth item.");
// myList.Capacity == 8

Clipping the capacity back

If you’re in a situation where you’ve added say 500 names from a database, but the capacity is going to be at 1024 at this point, it might be worth clipping back the capacity. Just call the TrimExcess method on the generic list instance.

myList.TrimExcess();

Initializing to a set size

And if you want to keep from potentially re-allocating memory as you add a lot of items, you can always initialize your list to a smart default number that is much larger than 0 or the default capacity of 4 by providing a size in the constructor.

List myList = new List(900);
// myList.Capacity == 900

Note that the capacity will exactly match the number you provide – it won’t jump up to the next exponent or anything like that. Of course it’s possible that behind the scenes the CLR is allocating a specific type of memory on the heap, but as far as numbers exposed to managed code, this is what you get.

Hope this helps.

Windows Phone performance progress bar update: part 2, remember to turn IsIndeterminate off when not needed!

Jeff Wilcox — Tue, 17 Aug 2010 21:38:28 +0000

Your application’s progress bar should look good, but it should minimize its cost as much as possible to ensure that the available CPU cycles are spent doing your hard work – parsing code, making and processing web requests, and responding to the user’s touch input – all of which happens on the UI thread.

On top of my previous post with a high performance progress bar, I’ve identified uses of progress bars where the IsIndeterminate value is hard-coded to True, and only visibility collapsing is used to show/hide the effect. This actually also has a negative effect on performance when not in use, as the animation defined when IsIndeterminate==True is continuous, forever looping, and going to have some effect on the main user interface thread just computing animation states, properties, and communicating with the core platform.

This came up as I was involved in a code review of a really sweet Windows Phone application that’s under development… Really sweet looking app, world class devs, and quality code – even a nicely architected lightweight model-view design. The application was using multiple indeterminate progress bars, plus my template, but was seeing performance degradation at times of 15-25 fps less than what we would hope for given the concious work to improve perf.

Turns out, having a bunch of progress bars on screen, with Indeterminate mode on, but collapsed, was still having a toll on the frame rates as all animations incur some cost, even if you never see them on screen.

This was an easy fix and I wanted to add this as guidance for having a good experience with progress bars in your phone apps.

1: Use PerformanceProgressBar over the built-in ProgressBar style

Step one: please use my PerformanceProgressBar in your application. It’s very easy to add in about 5 minutes and will pay dividends as your app gets faster. Progress bars as especially important to have low cost as they typically are only shown during potentially expensive operations.

As a recap, the IsIndeterminate=”True”/> control built into the platform has an adverse effect on the user interface thread’s frame rate. This is because it the indeterminate animation is built up of 5 sliding rectangles, built from Slider controls with custom thumbs, and all that work needs to happen five times over every single frame on the UI stack. You can read more about it if you like.

2: Turn off IsIndeterminate when not needed

When looking at this particular app, this was being used to show/hide the indeterminate progress bar. It means that the continuous animations and storyboard is always costing computing resources, so this is not what you want.

Try not to do this:

Now this should have also data bound the IsIndeterminate property. Since there’s a Visibility converter being used already here, this is an easy fix – just directly bind the bool property that the converter was using as an input. So this is additive.

Do try this:

So to properly “turn off” the indeterminate (continuous animation) from the progress bar, whether using the built-in progress bar or the template in my performance progress bar, you want to:

Bind or set the IsIndeterminate property: It should be False when you no longer need the continuous animations
Collapse the Visibility of the progress bar when not needed

Hope this helps.

Blend tip: finding default styles using “Edit a Copy”

Jeff Wilcox — Thu, 12 Aug 2010 00:43:42 +0000

If you’ve spent much time re-templating controls in Silverlight, WPF, or the Windows Phone, it’s clear that sometimes you want to understand the essence of a control through its template… but that XAML doesn’t feel easy to find at first glance.

Silverlight has the default styles and templates published on MSDN… for example, list boxes, content control, and auto complete box. You’ll find nice documentation with the actual template parts, visual states, and then the style that is built into the control library’s Themes\Generic.xaml resource dictionary.

However if you talk to an Expression Blend voodoo master, you will learn that it’s easier than searching on MSDN. Easy as in like 10 seconds.

Here’s a quick tutorial to something that comes up pretty often on discussion lists. I’m going to grab the

Looking ahead: Panorama and Pivot controls for Windows Phone developers

Jeff Wilcox — Wed, 11 Aug 2010 05:10:42 +0000

Apps in Windows Phone 7 make it easy to explore and experience information thanks to two similar navigation controls: panorama and pivot controls. We’ve made it easy for developers to build applications with these experiences by putting these Silverlight controls and associated tooling in the next release of the free developer tools (didn’t make the beta).

The controls are simple & easy to use, but I’ve seen enough rumbling on forums to know that developers are anxious to learn more about their capabilities. In lieu of bits, I’m going to introduce these controls and how they appear from a simple API & XAML perspective, so that you’ll have what you need while planning your apps to know how these experiences can fit into your apps.

Note: this post contains pre-release information and is subject to change at any time.

Panorama control inside of the Visual Studio design surface for the Windows Phone 7.

Learning about the native experience

Since phones are just beginning to trickle out, if you’d like to see what the built-in applications look like, there’s some multimedia up at WindowsPhone7.com.

A panorama powers the people, music + videos, parts of Office, and more. Many of these have a large background and can be explored by panning and flicking between items. When you’re at one item, you will be able to see a little bit of the next item as well – a hint that there’s more to be explored. When you reach the far side of the panorama, you can keep going to wrap around to the beginning again, saving time.

A pivot control powers the e-mail and calendar pages, operating systems, etc. The top of the pivot control shows the headers for all the different items, and you can swipe and pan between the pages. Just like panorama, the control wraps infinitely – so when you reach the final item, instead of having to flick all the way back to the first item, you can just flick once more.

Key Features

Both of the controls are lightweight enough to have great performance, while visually engaging and responsive to touch. Some features:

Simple XAML and application programming interfaces
Standard items controls that feels natural to developers, individual items are built from PanoramaItem and PivotItem content controls
Complete data binding support, content template properties and item container styles
Automatic support for light and dark phone themes
Built-in touch navigation: flicks move quickly, while panning past a threshold and releasing the touch will snap to the next item
Beautiful easing animations for sliding during navigation
Extensibility offered through events, visual states, and the ability to re-template
Great tooling comes standard, including app and page templates

So let’s take a look at the two controls!

Panorama

A visual depiction of the actual contents of the panorama control stretching beyond the physical size of the screen.

From the UI design and interaction guide for Windows Phone 7, the UX folks say:

Unlike standard applications that are designed to fit within the confines of the phone screen, these applications offer a unique way to view controls, data, and services by using a long horizontal canvas that extends beyond the confines of the screen.

…

Elements of a panoramic application serve as the starting point for more detailed experiences.

…

The background image is the lowest layer and is meant to give the panorama its rich magazine-like feel. Usually a full-bleed image, the background is potentially the most visual part of the application.

As all things in design go, what is not on the screen is as important as what is there: the control has a lot of empty space that helps keep the eye focused on the rich experience and data.

Panorama XAML

The Panorama control is placed on pages of your application and accepts a title and a background. Panorama sections are defined by PanoramaItem controls, and each has a header. The Title and Header are easiest to use when you’re just inserting text, but they also have associated HeaderTemplate and TitleTemplate dependency properties for data binding scenarios.

About wide horizontal sections

The panorama allows for special sections that are wider than the screen. Built-in phone hubs often use this for sets of thumbnails, albums, and other displays. If this is the appropriate effect you want for a section, make sure that the PanoramaItem declares that intent by setting the orientation to horizontal. Here’s what the minimized XAML looks like:

Panorama APIs

The key application programming interface for the Panorama builds on top of ItemsControl: so you get the standard items control properties (Items, ItemsSource, etc.), but also additional properties for setting the header, title, and reacting to the currently selected items by the user.

Microsoft.Phone.Controls.Panorama

Dependency Properties

DefaultItem

Sets the default item that moves into display. Allows your application to store the user’s most recently used panorama item to return to it later, just like the native operating system’s built-in hubs.
HeaderTemplate
SelectedIndex
SelectedItem
Title
TitleTemplate

Events

SelectionChanged

Allows the developer to hook up to selection changes (navigations from one panorama item to another).

Microsoft.Phone.Controls.PanoramaItem

Dependency Properties

Header
HeaderTemplate
Orientation

Setting the orientation to Horizontal will allow the item to be of a larger size than the control so that the user can pan and navigate within it. By default, this property is Vertical, which means that panning or flicking should instead bring you to the next panorama section.

Pivot control

The pivot control is a lot like the a tab control, but designed specifically for the phone and touch interaction. The entire pivot control (often the size of the screen and the root element on a page) can be panned, flicked, and manipulated – it’s not just about those headers (though those can be touched to navigate, too).

A simple pivot sample application running in the emulator. Notice that the phone’s theme in the emulator has been set to the light theme, and the control just works without the developer having to do anything.

From the design guidelines document:

A pivot control provides a quick way to manage views or pages within the application. This control can be used for filtering large datasets, viewing multiple data sets, or switching application views. The control places individual views horizontally next to each other, and manages the left and right navigation. Flicking or panning horizontally on the page cycles the pivot functionality.

Pivot XAML

Pivot APIs

Microsoft.Phone.Controls.Pivot

Dependency Properties

HeaderTemplate

A single data template that can be used for all headers in data binding scenarios.
SelectedIndex
SelectedItem
Title
TitleTemplate

Events

LoadedPivotItem
LoadingPivotItem
SelectionChanged
UnloadedPivotItem
UnloadingPivotItem

Microsoft.Phone.Controls.PivotItem

Pivot item is a simple content control and does not have any other special properties.

Visual Studio & Expression Blend Tooling

The tools are fully integrated with the design tools: if you click on an item in XAML, that item will become the one active in the design surface. There’s also an easy way to add additional items, well-defined control property editing, and so this all makes it really easy to get started building immersive apps.

Start with a complete application template

You can start off with an app powered by a panorama or pivot control: File > New Project has built-in templates for these apps.

Add New Pages

When you want to add a new Windows Phone page to your app, you can also add one that’s all ready to go with either a panoramic experience or pivot control, too. Just go to the Project menu and select Add New Item:

This makes it really easy to build out applications as quick as you can click.

Blend Assets

If you need to add either control to an existing app, in Blend you’ll find them in the Assets window, so they’re right where you’d expect to find them when you need ‘em.

Easy property editing

Key properties are easily accessible in the property editor. In this screen capture, you can see how easy it is to change an item to Horizontal mode, or to change the Header property:

Right-click, add new panorama item or pivot item

Integrated into the design surface you can also add extra items to the controls by right-clicking.

Visual Studio design surface

Expression Blend

Other notes

The controls can be found in the Microsoft.Phone.Controls namespace of the Microsoft.Phone.Controls.dll assembly, installed with the official Windows Phone Developer Tools.

As we get closer to launch, I’m sure we will have a good list of caveats and suggestions for the controls. Here are a few things that I had in mind that I wanted to share ahead of time, in case you are designing your application experiences and pages today.

Exposing scrolling data

If you look at applications on the phone such as Mail, you’ll often see that the Pivot control is used to filter and sort data. So when you move to the “unread” pivot item, you have unread mail items; flicking your finger again, you’ll get to “flagged”, listing the messages that you have flagged.

You could easily have hundreds of items in a single pivot item.

If you want to enable scrolling, you must either use a scrolling control like ListBox, or add a ScrollViewer to the pivot or panorama item. Scrolling is not enabled by default. This helps ensure that items are always sized to the parent container like you’d expect in the Silverlight-powered layout system.

Here’s how to add a scroll viewer or list box to a pivot item. Note that you’ll only want to offer a vertical scrolling experience, since horizontal manipulations (pan or flick) are part of the navigation experience with these two controls.

The example uses data binding to the data context, as well as custom-defined data templates from the application’s resources, so don’t just paste it into your app… but you get the idea I hope.

Items control API

These controls do both derive from ItemsControl, but they do have subtle differences.

Both controls

Items can be added in XAML
Items can be added in code, Items.Add(new PivotItem(…)) or Items.Add(new PanoramaItem(…))
ItemsSource can be used for data binding
Do not support alternative types of items: Pivot controls must use PivotItem, Panorama must have PanoramaItem

Differences

Panorama exposes a DefaultItem property
SelectedIndex and SelectedItem are settable in Pivot but not in Panorama

Migration

There are a number of alternative implementations of these controls out there, so for release, we’ll be working to blog guidance on migrating from one of those other experiences to these controls if you would like to.

Stay tuned!

Hope this helps prepare to design and build apps. I’ll be posting again once we release so that you can get started with panorama and pivot control!

TiltContentControl for Windows Phone

Jeff Wilcox — Sat, 07 Aug 2010 23:07:52 +0000

An enjoyable feature found in Windows Phone is a neat interactive effect that our designers have dubbed “tilt”. Tilt gives a little motion to standard controls during manipulations (when they’re being touched).

Although the operating system’s menus and core applications use this effect in many places, applications built for the platform by default don’t pick up any tilt effects. It’s a pretty complex problem to try and make assumptions about which controls and interface elements users would like to have a tilt added to.

We decided for now not to include the tilt effect for Silverlight apps on the phone, which is why you don’t see the tilt in the beta of the phone developer tools.

It’s a subtle effect, but you do see it when you use a device. It lets you know something’s responsive. So, if you click on the N in New Orleans in a list box like the one I have in a sample below:

Tilt in effect: the New Orleans entry has been touched and has tilted in reaction to the manipulation. When the manipulation is done, it will move back to its standard position.

Introducing Luke’s TiltContentControl

So one of our excellent devs on the Silverlight mobile team, Luke Longley, went ahead and coded up this control we’re calling TiltContentControl. I’m sharing this control on his behalf today as we wanted to get this out for people to experiment with.

This lets you wrap any element that you’d like to have receive a tilt-like experience. You can also add it to data templates or re-template controls like Button to make it easy to apply throughout your app in a standard way.

ContentControl vs Attached Property

Since this control derives from ContentControl, it is designed to wrap a single control that should have the effect. It can also be placed inside of custom templates and styles to make it easy to apply, instead of having to manually wrap all controls you’d like to tilt enable with the control.

Another approach other than using a wrapping content control is to use an attached property. Peter Torr from the Windows Phone application platform team created an implementation of tilt that does just that.

Both these implementations are slightly different, so check them both out – they’re interesting lessons in the platform. This content control responds to manipulation deltas, so you’ll get a very similar effect to that of the rest of the phone controls while your finger is still on the screen.

Adding the control to your project

As a simple derived content control, you can add TiltContentControl to your project just by dropping this single C# file into your project.

TiltContentControl.cs (code also duplicated below)

How to use the control within your project

So here’s how to use it in-place:

Here’s how to re-template something to use it – in this case I’m retemplating Button. You could put this style one time in your project, in App.xaml or a resource dictionary, then easily use it wherever without having to actually wrap the individual control instances.

So to have a Button use it, just set the style to the static resource:

The XML namespace I’m using (this should go at the top of any pages or resource dictionaries you place the tilt content control in):

xmlns:unofficial="clr-namespace:Microsoft.Phone.Controls.Unofficial"

Now in the sample image above, I show a ListBox with items that all have the tilt effect enabled. Here’s how you can do the same by adding the control within a data template and setting that to the ItemTemplate of your list box. I also have ended up using ItemContainerStyle to make the entire width of the item tilt-enabled:

I’m sure there are other ways to do this, too. Which type of solution is really up to you.

Creating and using a custom easing function

The easing function defined for the tilt up operation is not a standard one found in Silverlight. As a result, the choice is either to implement a custom easing function in C#, or to find a similar one in the platform.

Here’s what the UX people say:

Silverlight’s easing functions take in a normalized time value from 0 to 1. This means that if the double animation is really one second-long duration, then at half a second (500ms) the normalized time value will be 0.5, and at one second, 1.0. But never outside the range of [0, 1].

To implement a custom easing function, you just create a new class that derives from EasingFunctionBase from the System.Windows.Media.Animation namespace. The tilt control has this as a nested private class, since we aren’t exposing it for use elsewhere.

/// 
/// An easing function of ln(t+1)/ln(2).
/// 
private class LogarithmicEase : EasingFunctionBase
{
    /// 
    /// Constant value of ln(2) used in the easing function.
    /// 
    private const double NaturalLog2 = 0.693147181;

    /// 
    /// Overrides the EaseInCore method to provide the logic portion of
    /// an ease in.
    /// 
    /// Normalized time (progress) of the
    /// animation, which is a value from 0 through 1.
    /// A double that represents the transformed progress.
    protected override double EaseInCore(double normalizedTime)
    {
        return Math.Log(normalizedTime + 1) / NaturalLog2;
    }
}

We’ve only overwritten the EaseIn method here. Pretty simple, you don’t need to be a mathematician!

In code, you can just use an instance of the LogarithmicEase type now for any animation’s EasingFunction value. You’ll see this implementation has a single static readonly instance of it that’s reused every time.

Quick perf lesson #1: Avoid custom easing functions as they have a negative performance implication

Custom easing functions are called per frame on the user interface thread. This is a much more expensive operation than a standard easing function which is implemented in native code by Silverlight, and able to run in the compositor thread (previously known as the render thread or independent animations thread).

The callback into C# is time that the user interface thread could have spent handling operating system events, handling input, letting property change notifications propagate, or the layout system to perform a full measure-arrange pass.

We’ve decided to use a custom easing function because the platform’s designers have explicitly designated this as the tilt-up animation’s ease.

Quick perf lesson #2: Store a single static instance of property paths when creating animations in code

If you look through the code, you’ll see that the storyboard and double animations are created in code. To minimize the additional number of new object allocations, the code has 3 static readonly properties for the paths.

/// 
/// Single instance of the Rotation X property.
/// 
private static readonly PropertyPath RotationXProperty = new PropertyPath(PlaneProjection.RotationXProperty);

/// 
/// Single instance of the Rotation Y property.
/// 
private static readonly PropertyPath RotationYProperty = new PropertyPath(PlaneProjection.RotationYProperty);

/// 
/// Single instance of the Global Offset Z property.
/// 
private static readonly PropertyPath GlobalOffsetZProperty = new PropertyPath(PlaneProjection.GlobalOffsetZProperty);

This decreases the number of objects that have to be allocated, which decreases the cost of garbage collection. It’s probably a minimal improvement, but it’s something to think about.

Does this tilt exactly match the OS?

No, the effect doesn’t completely match.

The phone has an additional feature, a “global camera,” that I’m told takes into account the element’s position on screen. The global camera effect is why buttons near the bottom of the screen have an exaggerated tilt effect.

You won’t get that specific effect from this Silverlight implementation today. So this Silverlight implementation is more simple, but in my mind still achieves the goal of offering the tilt effect on elements.

We’ll see how people like it and maybe we’ll find a way to match the platform even closer in the future.

Workaround note for beta tools developers

There was a bug in the beta release of the platform where objects within a perspective transform that used bitmap caching would not necessarily react to the changing perspective. We’ve since fixed this internally.

To enable this file to be relevant to developers today (using beta tools) as well as in the future, I’ve coded in a workaround for beta tools users.

If you are using Beta tools, you should uncomment the #define statement near the top of the file (line 13 I think).

If you’re using post-beta tools, you can hopefully just use the file as-is.

Full implementation of TiltContentControl.cs

Here’s the full implementation, you can just drop this into your phone project:

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

// ---
// Important Workaround Note for developers using the BETA:
// There is a workaround in code that removes any CacheMode from the content of
// the control. It works around a platform bug that is slated to be fixed for
// release.
//
// If you are using the beta tools, remove the comment below:
// #define WORKAROUND_BITMAP_CACHE_BUG
// ---

using System;
using System.Diagnostics;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;

namespace Microsoft.Phone.Controls.Unofficial
{
    /// 
    /// A content control designed to wrap anything in Silverlight with a user
    /// experience concept called 'tilt', applying a transformation during
    /// manipulation by a user.
    /// 
    public class TiltContentControl : ContentControl
    {
        #region Constants
        /// 
        /// Maximum angle for the tilt effect, defined in Radians.
        /// 
        private const double MaxAngle = 0.3;

        /// 
        /// The maximum depression for the tilt effect, given in pixel units.
        /// 
        private const double MaxDepression = 25;

        /// 
        /// The number of seconds for a tilt revert to take.
        /// 
        private static readonly Duration TiltUpAnimationDuration = new Duration(TimeSpan.FromSeconds(.5));

        /// 
        /// A single logarithmic ease instance.
        /// 
        private static readonly IEasingFunction LogEase = new LogarithmicEase();

        #endregion

        #region Static property instances
        /// 
        /// Single instance of the Rotation X property.
        /// 
        private static readonly PropertyPath RotationXProperty = new PropertyPath(PlaneProjection.RotationXProperty);

        /// 
        /// Single instance of the Rotation Y property.
        /// 
        private static readonly PropertyPath RotationYProperty = new PropertyPath(PlaneProjection.RotationYProperty);

        /// 
        /// Single instance of the Global Offset Z property.
        /// 
        private static readonly PropertyPath GlobalOffsetZProperty = new PropertyPath(PlaneProjection.GlobalOffsetZProperty);
        #endregion

        /// 
        /// The content element instance.
        /// 
        private ContentPresenter _presenter;

        /// 
        /// The original width of the control.
        /// 
        private double _width;

        /// 
        /// The original height of the control.
        /// 
        private double _height;

        /// 
        /// The storyboard used for the tilt up effect.
        /// 
        private Storyboard _tiltUpStoryboard;

        /// 
        /// The plane projection used to show the tilt effect.
        /// 
        private PlaneProjection _planeProjection;

        /// 
        /// Overrides the method called when apply template is called. We assume
        /// that the implementation root is the content presenter.
        /// 
        public override void OnApplyTemplate()
        {
            base.OnApplyTemplate();
            _presenter = GetImplementationRoot(this) as ContentPresenter;
        }

        /// 
        /// Overrides the maniupulation started event.
        /// 
        /// The manipulation event arguments.
        protected override void OnManipulationStarted(ManipulationStartedEventArgs e)
        {
            base.OnManipulationStarted(e);

            if (_presenter != null)
            {
#if WORKAROUND_BITMAP_CACHE_BUG
                // WORKAROUND NOTE:
                // This is a workaround for a platform bug related to cache mode
                // that should be fixed before final release of the platform.
                UIElement elementContent = _contentElement.Content as UIElement;
                if (elementContent != null && elementContent.CacheMode != null)
                {
                    elementContent.CacheMode = null;
                }
#endif
                _planeProjection = new PlaneProjection();
                _presenter.Projection = _planeProjection;

                _tiltUpStoryboard = new Storyboard();
                _tiltUpStoryboard.Completed += TiltUpCompleted;

                DoubleAnimation tiltUpRotateXAnimation = new DoubleAnimation();
                Storyboard.SetTarget(tiltUpRotateXAnimation, _planeProjection);
                Storyboard.SetTargetProperty(tiltUpRotateXAnimation, RotationXProperty);
                tiltUpRotateXAnimation.To = 0;
                tiltUpRotateXAnimation.EasingFunction = LogEase;
                tiltUpRotateXAnimation.Duration = TiltUpAnimationDuration;

                DoubleAnimation tiltUpRotateYAnimation = new DoubleAnimation();
                Storyboard.SetTarget(tiltUpRotateYAnimation, _planeProjection);
                Storyboard.SetTargetProperty(tiltUpRotateYAnimation, RotationYProperty);
                tiltUpRotateYAnimation.To = 0;
                tiltUpRotateYAnimation.EasingFunction = LogEase;
                tiltUpRotateYAnimation.Duration = TiltUpAnimationDuration;

                DoubleAnimation tiltUpOffsetZAnimation = new DoubleAnimation();
                Storyboard.SetTarget(tiltUpOffsetZAnimation, _planeProjection);
                Storyboard.SetTargetProperty(tiltUpOffsetZAnimation, GlobalOffsetZProperty);
                tiltUpOffsetZAnimation.To = 0;
                tiltUpOffsetZAnimation.EasingFunction = LogEase;
                tiltUpOffsetZAnimation.Duration = TiltUpAnimationDuration;

                _tiltUpStoryboard.Children.Add(tiltUpRotateXAnimation);
                _tiltUpStoryboard.Children.Add(tiltUpRotateYAnimation);
                _tiltUpStoryboard.Children.Add(tiltUpOffsetZAnimation);
            }
            if (_planeProjection != null)
            {
                _width = ActualWidth;
                _height = ActualHeight;
                if (_tiltUpStoryboard != null)
                {
                    _tiltUpStoryboard.Stop();
                }
                DepressAndTilt(e.ManipulationOrigin, e.ManipulationContainer);
            }
        }

        /// 
        /// Handles the manipulation delta event.
        /// 
        /// The manipulation event arguments.
        protected override void OnManipulationDelta(ManipulationDeltaEventArgs e)
        {
            base.OnManipulationDelta(e);
            // Depress and tilt regardless of whether the event was handled.
            if (_planeProjection != null)
            {
                DepressAndTilt(e.ManipulationOrigin, e.ManipulationContainer);
            }
        }

        /// 
        /// Handles the manipulation completed event.
        /// 
        /// The manipulation event arguments.
        protected override void OnManipulationCompleted(ManipulationCompletedEventArgs e)
        {
            base.OnManipulationCompleted(e);
            if (_planeProjection != null)
            {
                if (_tiltUpStoryboard != null)
                {
                    _tiltUpStoryboard.Begin();
                }
                else
                {
                    _planeProjection.RotationY = 0;
                    _planeProjection.RotationX = 0;
                    _planeProjection.GlobalOffsetZ = 0;
                }
            }
        }

        /// 
        /// Updates the depression and tilt based on position of the
        /// manipulation relative to the original origin from input.
        /// 
        /// The origin of manipulation.
        /// The container instance.
        private void DepressAndTilt(Point manipulationOrigin, UIElement manipulationContainer)
        {
            GeneralTransform transform = manipulationContainer.TransformToVisual(this);
            Point transformedOrigin = transform.Transform(manipulationOrigin);
            Point normalizedPoint = new Point(
                Math.Min(Math.Max(transformedOrigin.X / _width, 0), 1),
                Math.Min(Math.Max(transformedOrigin.Y / _height, 0), 1));
            double xMagnitude = Math.Abs(normalizedPoint.X - 0.5);
            double yMagnitude = Math.Abs(normalizedPoint.Y - 0.5);
            double xDirection = -Math.Sign(normalizedPoint.X - 0.5);
            double yDirection = Math.Sign(normalizedPoint.Y - 0.5);
            double angleMagnitude = xMagnitude + yMagnitude;
            double xAngleContribution = xMagnitude + yMagnitude > 0 ? xMagnitude / (xMagnitude + yMagnitude) : 0;
            double angle = angleMagnitude * MaxAngle * 180 / Math.PI;
            double depression = (1 - angleMagnitude) * MaxDepression;
            // RotationX and RotationY are the angles of rotations about the x-
            // or y-axis. To achieve a rotation in the x- or y-direction, the
            // two must be swapped. So a rotation to the left about the y-axis
            // is a rotation to the left in the x-direction, and a rotation up
            // about the x-axis is a rotation up in the y-direction.
            _planeProjection.RotationY = angle * xAngleContribution * xDirection;
            _planeProjection.RotationX = angle * (1 - xAngleContribution) * yDirection;
            _planeProjection.GlobalOffsetZ = -depression;
        }

        /// 
        /// Handles the tilt up completed event.
        /// 
        /// The source object.
        /// The event arguments.
        private void TiltUpCompleted(object sender, EventArgs e)
        {
            if (_tiltUpStoryboard != null)
            {
                _tiltUpStoryboard.Stop();
            }
            _tiltUpStoryboard = null;
            _planeProjection = null;
            _presenter.Projection = null;
        }

        /// 
        /// An easing function of ln(t+1)/ln(2).
        /// 
        private class LogarithmicEase : EasingFunctionBase
        {
            /// 
            /// Constant value of ln(2) used in the easing function.
            /// 
            private const double NaturalLog2 = 0.693147181;

            /// 
            /// Overrides the EaseInCore method to provide the logic portion of
            /// an ease in.
            /// 
            /// Normalized time (progress) of the
            /// animation, which is a value from 0 through 1.
            /// A double that represents the transformed progress.
            protected override double EaseInCore(double normalizedTime)
            {
                return Math.Log(normalizedTime + 1) / NaturalLog2;
            }
        }

        /// 
        /// Gets the implementation root of the Control.
        /// 
        /// The DependencyObject.
        /// 
        /// Implements Silverlight's corresponding internal property on Control.
        /// 
        /// Returns the implementation root or null.
        public static FrameworkElement GetImplementationRoot(DependencyObject dependencyObject)
        {
            Debug.Assert(dependencyObject != null, "DependencyObject should not be null.");
            return (1 == VisualTreeHelper.GetChildrenCount(dependencyObject)) ?
                VisualTreeHelper.GetChild(dependencyObject, 0) as FrameworkElement :
                null;
        }
    }
}

Namespace: Microsoft.Phone.Controls.Unofficial

One change since the ProgressBar template I blogged about: I’m using the namespace Microsoft.Phone.Controls.Unofficial now. Unsupported sounded harsh; obviously these types of controls will be improved upon over time and they’re out in the public, so either on StackOverflow.com or Twitter or whatever there will be some place for people to talk about what’s good and bad with these controls.

Hope this helps.

Creating high performance Windows Phone apps – THE WHITEPAPER

Jeff Wilcox — Sat, 07 Aug 2010 18:53:24 +0000

Our perf whitepaper has made it out in the wild, please take a look at “Creating high performance Silverlight applications for Windows Phone” – the download includes not only the whitepaper, but also sample applications.

Some of the features it covers:

Compositor thread and user interface thread
Frame rate counter & cache visualizations
Cache mode
Fill rate concepts
Loading images larger than 2000 x 2000
Navigating into pages in other assemblies

Some tips it includes:

Using Opacity = 0 to hide objects and reduce the fill count
Using images over XAML for some graphics that don’t need to be vectors
Minimizing the code in constructors and initialization code paths
Using Dispatcher.BeginInvoke at startup to get initialization work happening quickly, but after rendering the screen
Using async

It includes sample apps that demonstrate concepts:

Examples about fill rate
How to hide objects using Opacity = 0
Loading large images
Per-frame callback implications
How to split code across DLLs to improve app startup time

This was created by performance experts on the phone and Silverlight teams, and even I’ve even contributed to the whitepaper – the frame rate counters image from my blog is in there.

I’ll also be covering many of these topics in depth on this blog going forward.

Hope this helps.

A high performance ProgressBar for Windows Phone

Jeff Wilcox — Mon, 02 Aug 2010 12:01:10 +0000

The ProgressBar template for Silverlight that is built into the Windows Phone today looks beautiful but comes at a cost to performance in indeterminate mode (the animating dots that often indicate loading during an operation of unknown time).

Here I offer a workaround which is identical in looks, but with excellent performance. It uses the render thread exclusively for animation, instead of the UI (user interface) thread. I’ve touched on this previously in a post of performance and frame rate counters for the Windows Phone.

8/17/10 Update

A quick update since I originally posted this on August 2nd: you should also take care to toggle the IsIndeterminate property through binding or code when not needed, on top of collapsing the visual of the control. This was identified through app code reviews and is another important part of speeding up your apps. More info in my 8/17 post.

The original post follows:

Moving the indeterminate animation to the render thread frees up the UI thread to handle application events, messages, interact with the networking stack, and otherwise keep the app running smoothly.

Using the PerformanceProgressBar in your app

This workaround requires you to add a simple control (a .cs file) to your Windows Phone project, as well as set the ProgressBar style to the alternative, and should take about 5 minutes. This is what you want if you want to give your users that “progress indicator” visual style while data or information is loading, and using this version will let the app continue to look responsive to your customers.

Get the code

Download and add the source file RelativeAnimatingContentControl.cs to your project (it is open source)

Add the PerformanceProgressBar style

Open the App.xaml file in your Windows Phone project (or generic.xaml if a composite control library). Next, add the following XMLNS declaration at the top element – this is important as it tells the parser to look in your project for the code you added above:

xmlns:unsupported="clr-namespace:Microsoft.Phone.Controls.Unsupported"

Now, go into the Resources section of the file and add this style (you can also download as PerformanceProgressBarStyle.txt):

Add this alternate ProgressBar control style everywhere

Now, whenever you or your designers place a ProgressBar in your app, set the style to be PerformanceProgressBar and it will be picked up from the App.xaml.

In XAML:

In code:

Style style = (Style)App.Current.Resources["PerformanceProgressBar"];
if (style == null) { throw new InvalidOperationException("The style was not found."); }
ProgressBar bar = new ProgressBar
{
    IsIndeterminate = true,
    Style = style,
};
LayoutRoot.Children.Add(bar);

That’s it! Read on if you want to learn about how this all actually works, why it isn’t built into the system (there’s a good reason), and just general info about the performance-improving workflow I went through.

The back story

When people started seeing poor performance on applications that were using indeterminate progress bars, it was a stumper. I’m pretty sure there were hallway conversations including: “what the heck? how’s this so bad? there’s nothing happening here – it’s just animating rectangles! WTF? is there a bug in the animation system? what’s really the issue? this is a super simple animation! fix it!”

I jumped in and started looking at the root of the potential performance problem. It was definitely interesting because the emulator experience was pretty good (though still heavy in the UI thread), but once these same apps were on real developer devices, the issue manifested. The emulator is just that – it emulates, so there will be differences.

Working to unpeel the onion and diagnose the indeterminate ProgressBar as the root of the performance issue, some of what was tried:

Noting applications were sluggish on hardware devices when a progress bar would appear in indeterminate mode
Removing networking calls, commenting out any data parsing, and cutting out application logic – leaving just simple states and the progress bar
Building a repro application with an indeterminate ProgressBar, the UI thread was still stressed according to the frame rate counters
Adding several progress bars compounded the problem
Trying to understand why the render thread frame rate was doing fine (above 50 fps), but the UI was below 10 fps at times
Reviewing the default control style and template’s visual state animations and code to look for complex animations or opportunities for improvement (BitmapCache was not being used for instance, but it wasn’t a big enough difference to explain the cause)
Identifying that the method used to move the small rectangles on the screen by animating the Value property of Slider would cause per-thread callbacks to the property change handler of the Slider control, forcing the animations to the UI thread instead of the independent animations render thread

So there, the issue was in the animations and underlying template for the indeterminate ProgressBar and its use of Slider controls.

Why Slider is in the template

The default style and control template for the Windows Phone was created to meet the UX & user interface guidelines that the Windows Phone team has created. A consistent and good-looking set of controls is an important part of the platform and so the progress bar has a very slick appearance.

In “indeterminate” mode, five small rectangles in the user’s accent color, that move into the screen one just briefly after another. It’s mesmerizing and more fun than the standard Silverlight one you may have seen on the web before.

Trouble is, the animation defined for the rectangles is impossible to declare in XAML markup – there’s no way to provide an animation frame description which says “at this keyframe, the rectangle should be positioned 1/3 of the width of the control”: Silverlight happily will let you define a specific fixed position (like translating 75 pixels), but not a variable or ratio-based size for the animation.

But wait! There’s another control in the core platform that can do this visual concept.

Enter Slider. Slider is a nice control because it calculates a position based on the width and effectively a percent (the Value divided by the Maximum provides the ratio), then uses that to update the Thumb/Track template part of the control.

Here’s some short XAML that helps demonstrate how this ratio works for offsetting the thumb:

And you’ll see that even though the Value is 30 in each case, the Sliders are different sizes based on their parents’ size: effectively allowing for moving the thumb based on a ratio applied to the actual width:

This let the designers create the ratio-based animation for the rectangles (thumbs of a slider) that makes them smoothly move in thirds. The rectangles enter to one third the width of the screen while fading in, then move at a different rate from 1/3 to 2/3 the width of the screen, and then fly and fade out.

So indeterminate mode progress bar was destined to use a set of Sliders to move those rectangles. The progress bar defines 5 Slider controls.

Here’s a snippet from the default style template in the beta release of the Windows Phone developer tools:

The static style resource defines a custom look for the Slider to create an accent colored rectangle, instead of looking like the normal phone Slider control you may place on the page.

Nesting controls within templates is how Silverlight was designed to work, so it isn’t the composition of controls that necessarily degrades performance in this case (though simplicity is always key, especially on a device that has very different computing properties than your PC).

Now here’s a small chunk of the Storyboard animation code that animates the Slider instances. Note the Value target property:

And now we are finally to the root of the problem: the trouble is that Value is a DependencyProperty defined by the nested Slider controls, and it has some performance implications.

Animating the Slider::Value property means the animation happens on the UI thread (not good!)

The Value DependencyProperty of Slider comes from its parent class, RangeBase. The declaration for the property shows that there is a property change callback, OnValueChanged, that is called whenever the property changes, so in our case, when the progress bar animations animate the Slider.Value target property – which will be every single frame, it’s an animation.

The platform allows dependency properties to optionally have these callbacks to perform logic and states changes, validation, and other operations. In real world control development, I’d guess that it’s 50/50 whether a property has that callback. So it’s not a design flaw of a property, they are there for a good reason, but can have unintended consequences to performance, especially once you start doing wild things with those properties.

If you open up Reflector to look at Slider, you’ll see a call to UpdateTrackLayout. This is the meat of the control that updates the size of the template’s special Grid columns or rows to simulate the movement of the Slider.

The callback will always happen on the UI thread, as all core UI interactions on the platform need to happen on the UI thread, and the runtime guarantees this.

That means that the five animations for the value property cannot happen on the separate render thread.

What needs to change in ProgressBar? Should we build our own?

So maybe the default style on the phone is a little “heavy”; but the ProgressBar control implementation is fine. There are no code fixes or changes required to the actual control.

I recommend just using a special C# file and re-templating the standard ProgressBar, though it would be easy enough to package this up into an independent control library or ship with some kind of toolkit. We’ll see what people do.

Why can’t MSFT update the progress bar in the platform?

I’m really only talking here about the beta version of the developer tools for the Windows Phone.

In my opinion, changing this in the platform while matching the Windows Phone user interface guidelines is a big technical challenge (again, the lack of ratio-based translation key frames in Silverlight), so in the meantime, please use mine – I’ll make sure it continues to work through the release of the phone and will blog and tweet updates as necessary.

This could change in the future, but since this workaround doesn’t change the ProgressBar control itself, it is easy enough to pull out the workaround – just remove the custom Style setter!

Shouldn’t everything just be fast and have great performance anyway?

We all wish. There is a lot of give and take in application development and especially tweaking for perf.

On the Silverlight mobile team we’re very serious about performance, but don’t expect performance to be free: we’re doing our part to drive performance improvements through the product, but we need application developer’s help as well to optimize their applications for the phone experience.

What’s this RelativeAnimatingContentControl I added to my project?

I designed this custom content control that makes adjustments to the storyboards of the visual states attached to it. When the layout is updated (i.e. there is a known size), the control will go through the storyboards and update the properties that are designed to be “relative”, using its initial ratio.

The control has some magic number trickery to accomplish this, and only works with double animation elements and double animations with key frames. Instead of hard-coding numbers and using that, the control interprets the initial values of the animation properties as a percentage. If you’re interested in the inner workings, let me know and I am happy to post more about it. Quickly, if a From, To, or keyframe Value has an initial value ending in “.1” (such as 33.1, or 75.1, or 0.1), the property is interpreted as a percentage ratio based on the width of the control – 0 to 100. The .1 is stipped off. If the magic number decimal is instead .2, like 50.2, then the height of the control is used for the calculation instead. The idea is that a designer and coder work to define the special template with these magic numbers, but it doesn’t keep the designer from defining other animations that are not ratio-based.

Since the control must be the root of the ProgressBar template, it is an opt-in model and won’t affect any other uses of ProgressBar either.

This is all to work around the lack of ratio animation properties in Silverlight, and it’s a pretty good solution, magic numbers aside. I feel a little sick about the magic numbers part. I’m sharing this feedback with the team of course and we’ll see what the future holds.

Why’s the control in the Microsoft.Phone.Controls.Unsupported namespace?

I wanted to make it clear to everyone that this is not an official Microsoft control. It’s a way to work around a limitation in Silverlight, and probably not a good general-purpose solution.

That said, the namespace probably should be JeffWilcox.Controls.Supported: I’m always happy to look at the feedback I get on these posts and update the content to be relative and address issues.

What changed in the PerformanceProgressBar style

You’ll see that the ProgressBar style looks very similar. Here are some of the differences:

The root of the control template is this special RelativeAnimatingContentControl. The control updates the visual state storyboards when the size of the control changes, giving the animations a ratio to the size of the control based on the initial value stored in the storyboard.
The 5 Slider controls have been replaced by 5 simple Rectangle instances
The rectangles have BitmapCache turned on
Each rectangle has a defined TranslateTransform which is used to move the rectangle instead of the UI animation from the standard (which animated the Value property, on the UI thread, which then made the item move after a layout pass with the underlying grid in the template)

So here’s the part with the rectangles:

And here’s some of the animation code. Note the “magic” numbers ending in 0.1 – those tell the system it’s a ratio based on the width of the control. A hacky overload of a property, but something that can work and give us a real perf win today!

Feedback

I hope everyone uses this ProgressBar to make their apps rock. Remember that one key to great perf is to let the UI thread “breath”: don’t bog it down, let it do its job, and especially in loading, downloading and parsing scenarios, really important to use a progress bar that won’t inhibit the progress.

This is pre-release information and is subject to change. I’ll try and keep the post updated. Let me know how it goes!

Frame rate counters in Windows Phone

Jeff Wilcox — Mon, 26 Jul 2010 16:29:25 +0000

While developing Windows Phone applications, it’s good to have some simple but important performance tips and tricks in your back pocket. Here’s a quick reference to enabling frame rate counters plus an overview of what the values represent.

Enable frame rate counters in code

In your App.xaml.cs or MainPage.xaml.cs, in the constructor, set the host property to true for this diagnostic mode:

Application.Current.Host.Settings.EnableFrameRateCounter = true;

Make sure the System Tray is not visible

By default in the beta tools, the MainPage.xaml sets the system tray to be visible. When this happens, the frame rate counters are hidden by the operating system shell.

Method 1: XAML

The default page template includes an XMLNS declaration for “shell”, and has this in the phone application page constructor:

shell:SystemTray.IsVisible="true"

Just change the IsVisible property to False:

shell:SystemTray.IsVisible="false"

Method 2: Code

Microsoft.Phone.Shell.SystemTray.IsVisible = false;

In a future release of the phone tools, this is actually going to be less of an issue, as the counters will actually be right-aligned on the screen instead.

Adding a simple check box to toggle the counters

A lot of app developers add a check box to debug builds that lets them toggle this sort of diagnostic display. In one of our ‘Scenarios’ test applications, we have a check box on the first page, and in XAML it connects the Checked and Unchecked events to this method.:

private void FrameRateCounters_Checked(object sender, RoutedEventArgs e)
{
    var checkbox = (CheckBox)sender;
    var newValue = checkbox.IsChecked.GetValueOrDefault();

    Application.Current.Host.Settings.EnableFrameRateCounter = newValue;
    SystemTray.IsVisible = !newValue; // Hides frame rate counter otherwise
}

Enabling frame rate counters only on debug builds

You can also use conditional compilation to just have your debug builds display this information. Add this to your App.xaml.cs:

#if DEBUG
    Application.Current.Host.Settings.EnableFrameRateCounter = true;
    Microsoft.Phone.Shell.SystemTray.IsVisible = false;
#endif

This assumes you remember to eventually ship your app on the marketplace with a release build .

Accelerated graphics note: If you still don’t see a frame rate counter

The frame rate counter only appears when your system has a supported DirectX 10 graphics card that allows the Windows Phone emulator to use accelerated graphics.

If you set the frame rate counter visibility to True, the system tray is hidden, and you still don’t’ see the counters, then unfortunately your system does not have a supported card for displaying this information.

All Windows Phone devices will show the frame rate counter, so once phone hardware is more widely available, you’ll still have an option to test the performance of your apps.

Exploring the frame rate counter data

This has been covered countless times, but I figure if you’re [using your search engine of choice to find this] here that it doesn’t hurt to duplicate.

The Beta tools display frame counter information on the top of the page.

Shipping frame counter information is displayed on the right of the screen.

So moving through the counters, we have the following.

Render Thread FPS: The number of frames per second that the independent simple animations and rendering thread is using. Keeping around 60 will provide a great experience, while a number of 30 fps will begin to show a poor experience to the end user.

Under 30 fps this counter will turn red in post-beta builds.

User Interface Thread FPS: The number of fps that the primary user interface thread is experiencing. Property change notifications, data binding, primary managed code execution, and animations not handled on the render thread use this threads’ resources.

Turns red when the count is at or below 15 fps.

Texture Memory Usage: A specialized memory counter indicating the video memory used for storing application textures.

Surface Counter: A count of the number of surfaces that are passed to the graphics chip.

Intermediate Texture Count: The number of intermediate textures created for compositing.

Screen Fill Rate: A metric representing the number of complete phone screens being painted each and every frame.

This counter was not present in the Beta tools and is a new metric for post-Beta use.

Target frame rates for good performance

When testing on a Windows Phone device, here are key performance metrics to try for. Understand that the emulator (XDE) performance may not be indicative of actual device performance.

Frame rate counters may be 0 when there is no animation being updated on the thread at any particular moment. You can add a very simple, continually animating and repeating, animation to your application during development & testing if you want to ensure that there is always some frame rate value available.

Counter	Ideal Minimum	Best Experience	Theoretical Max
Render Thread	30 fps	60 fps	120 fps
UI Thread	15 fps	> 15 fps	120 fps
Screen Fill Rate	1.0	<= 2.0	N/A

Future posts will cover tips for improving the frame rate and application performance. Hope this helps.

Updated Silverlight Unit Test Framework bits for Windows Phone and Silverlight 3

Jeff Wilcox — Thu, 27 May 2010 21:02:52 +0000

Here are updated quasi-official unit test framework bits for Silverlight 3 and Windows Phone developers. These are not intended for Silverlight 4 developers, since the same framework built for SL4 is included in the April 2010 Silverlight Toolkit.

This brings the new features from the Silverlight 4 version to developers who have a business reason to continue with Silverlight 3 development for the time being:

Updated user interface
Integrated “tag expression” support for selecting subsets of tests to run
Performance improvements
Removal of dependencies on XLinq and System.Windows.Browser assemblies

These are also the bits you want for Windows Phone testing.

Why wasn’t there one for Silverlight 3 already?

Since the April 2010 toolkit release was targeted for Silverlight 4 developers only, these bits were not released for version 3 (though were built from the same source).

Why doesn’t the April 2010 toolkit work for Windows Phone development & testing?

The Windows Phone development environment is based on a version of Silverlight 3 today, and so that means that you need to use Silverlight 3 binaries and class libraries when re-using Silverlight apps and code – not Silverlight 4.

These bits work well for phone developers and replace the older bits I had posted to my MIX talk site.

Download the binaries

[Silverlight 3 binaries for the Silverlight Unit Test Framework, Zip 452KB]
You may need to ‘unlock’ the binaries for security reasons once downloading and extracting the assemblies from the .Zip. To do this, right-click on the file and select the ‘Unlock’ button.

These binaries are strong named as before, but are not Authenticode signed, so they are not official. This helps work around some Windows Phone signing issues I’ve heard reports of.

Hope this helps,
Jeff

How about a Zune-style ChildWindow?

Jeff Wilcox — Fri, 21 May 2010 21:25:39 +0000

Today I’m sharing my new ChildWindow style. It is a differentiated child window designed in that it doesn’t have a close button, has a completely different animation in and out, and I thought I was worth sharing. I’ve included a runtime app so you can run it and see for yourself.

My ChildWindow style

Click on the window above to open a simple Silverlight 4 application that demonstrates the transitions and interactivity. Project download.

Some things to call out:

I don’t include a Close button in the window chrome.
I hook up to the OnKeyDown event in my sample implementation. I always try and do this with my ChildWindows so that the escape (ESC) key can be treated as a cancelation of the dialog. Personal preference but a usability win I believe.
I like a light overlay color instead of a darkening experience, and went for that look.
My actual implementation uses a value converter to capitalize the title. I’ve removed this from my template for the time being.

The story on my evolving, unnamed theme, and how it relates to “Cosmopolitan”

There’s an excellent “Cosmopolitan” Silverlight project template + theme available that makes building good-looking interfaces a snap, and I’d highly recommend it if you’re looking to modernize the look of a new Silverlight project. I believe it pulls from “codename Metro” design ideas. It just works and as a VS template it rocks!

I’ve built an alternative, but similar theme, over time that I use on many of my projects, and it also pulls from the inspiration of the clean, consistent Zune software design principals.

Now that the “Cosmopolitan” theme is out there, I’ve been taking the time to compare and contrast my similar theme with this, and see where I can make changes. Yeah, the things I do in my free time are baffling…

This is a good exercise because design is a two-way street, comparing and contrasting design decisions and implementations: I’ve learned that I should have been including validation templates in my theme (oops, haven’t used that feature enough). And I’ve shared some minor feedback on parts of the “Cosmopolitan” theme’s implementation details with its designers.

In the future I’ll present the complete theme for many controls, but until that develops, I’m going to continue to share small styles and templates, along with my comments along the way. Previously I blogged my context menu style.

If you’re wondering “why should I use ChildWindow?” – I used to wonder the same thing. But I’m using ChildWindow more now than ever. I’ve discovered the importance of the nice integration with Visual Studio (there’s an item template for child windows), and out-of-browser applications have many uses for a rich modal-style window for sharing information at runtime.

I’ve completely replaced the MessageBox in my out-of-browser applications to instead use a child window designed to replace the message box functionality, offering a consistent visual design even when a message box-like experience is needed. I even use extension methods to add methods to MessageBox to instead use my styled child window.

Other ChildWindow styles

Here’s the standard ChildWindow style and control template that is built into the Silverlight SDK. I’m displaying a password entry form adapted from an app I was experimenting with:

Here is the same window with the “Cosmopolitan” theme’s style applied:

Note: There’s a bug in ChildWindow implicit styling support

While working on creating themes, I did discover that there’s an unfortunate bug in Silverlight 4 where the implicit styles for ChildWindow are not picked up in certain XAML scenarios. Namely, if you use the handy item template in Visual Studio, the implicit style won’t be picked up.

Oddly, at times Visual Studio will show the proper implicit style, but at runtime it will revert to the standard control default style. Here’s a small screenshot – this is out-of-the-box “Cosmopolitan” theme with a ChildWindow item template.

At design time it looks fine:

At runtime:

It appears that this item template format, where the XAML file of the child window’s root is the child window, doesn’t allow the style that was implicitly defined to be picked up.

No worries. To workaround this, add a Style attribute to the root of the file and a static resource to ChildWindow name. If you’re working with “Cosmopolitan”, then here are the steps:

Open the Assets/SDKStyles.xaml file
Navigate to the implicit style for ChildWindow around line 2,440
Add an x:Key to make the style explicit instead of implicit. x:Key=”ChildWindowStyle”
Add this line after the (now explicit) style:

Here’s how you reference it:

And now let’s make that into an implicit style for Silverlight 4. Just remove the x:Key:

And here’s how you reference that style – you don’t – it’s implicit:

Small caveat, fyi: there is a bug with implicit styles not necessarily being applied within data templates. To work around this, I had to move to explicit styles (adding an x:Key to the style, then setting the Style property in the DataTemplate’s XAML to the static resource’s key).

Local fonts

I also used a feature of Silverlight 4 that lets me pick up and use local fonts on the machine. I’m using the ‘Segoe UI’ font, a key part of the Windows 7 user experience and visual identity.

However I also define fallback fonts, just like you would in HTML:

My Zune-like context menu

Here are the templates I ended up creating using Expression Blend.

To achieve the fade-in effect, I faked a little and used a Loaded event trigger, so the first time any particular context menu is shown, it will quickly fade – but subsequent presentations of the same instance will not fade, for a faster, more performant feel.

ContextMenu Style

Separator Style

MenuItem Style

ZuneLikeContextMenuImplicitStyles.xaml.txt: XAML. Download all three in one file. The file contains both implicit styles plus defined style names.

Here’s a comparison, a screenshot of the Zune menu on the left, and my Silverlight 4 context menu on the right:

Hope this helps you create some nice modern-looking Silverlight apps!

Deep dive on Silverlight unit testing at Tech Ed next month

Jeff Wilcox — Tue, 11 May 2010 18:30:12 +0000

In about a month I will be presenting a 200-level session on Silverlight unit testing at Tech Ed North America in New Orleans. The talk will be an hour with questions, so you can arrive new to Silverlight testing and leave with all the tools you need to be successful in building high-quality applications with the right level of regression coverage that your management can smile about.

The session will be more comprehensive than the overview talk I presented at MIX 10 (which is available as a free online video stream now).

Click here to view the talk information on the Tech Ed site. The tentative information is as follows, but please double-check with the conference schedule builder before showing up:

Unit Testing in Microsoft Silverlight
Wednesday, June 9, 2010
11:45 AM – 1:00 PM
Room 287
Session Code WEB205
http://northamerica.msteched.com/topic/list?keyword=WEB205

Hope to see some friendly faces in the audience! I’ll be up there in some sort of speaker polo shirt uniform with khakis, apparently this conference isn’t quite as trendy and cool as MIX in Vegas .

If you’re going to be attending Tech Ed, I’d appreciate any early comments you have as there is still time to shape the content of the talk.

Silverlight Unit Test Framework: New version in the April 2010 Silverlight Toolkit

Jeff Wilcox — Mon, 03 May 2010 22:26:06 +0000

In April we released a new version of the Silverlight Toolkit for targeting Microsoft Silverlight 4. This release contains a new version of the Silverlight Unit Test Framework. Key improvements come in user interface, Silverlight 4 support, and performance.

Rich, modern user interface

The user interface no longer uses the antiquated HTML DOM bridge for displaying results, but now is a data bound, rich Silverlight application itself.

Rich results information is available, and a tree view control allows you to select results to be included in a test report that can be copied to the clipboard. Failures are automatically selected.

The results pane includes information about the tests that ran, as well as detailed information for failures.

Descriptive text helps identify negative tests, known test issues and bugs, and other important metadata that was not always exposed in the previous test framework.

Integrated tag expression support

The startup experience now allows you to enter a tag expression to select which tests to run, or not to run. You can add the Tag(“”) attribute to any test methods or classes to define your own tags. Also, the full and short names of tests and classes implicitly become test tags, as well as priorities.

This means that you can define tags such as:

!MyTest1	Run all tests except for the method named MyTest1
MyTest1+MyTest2	Run the MyTest1 and MyTest2 test methods

Out of Browser support

The framework now supports running out-of-browser. Paired with the new Silverlight 4 Tools for Visual Studio 2010, you can press F5 to run a test project you have marked as an out-of-browser.

This also opens up an opportunity to do testing of elevated apps that make use of AutomationFactory and other advanced features on Windows.

Simplified dependencies

The test framework removed dependencies on System.Windows.Browser (from the platform) and System.Xml.Linq (XLinq, from the SDK).

Building blocks for Windows Phone testing support

This version also contains the full source to the phone testing interface, which is significantly different in visual design and experience to coincide with the Windows Phone device size.

However, the story for phone testing is still developing: in the meantime binaries designed for phone use can be found at http://jeffatmix.com/

New location for binaries

Since the new rich user interface contains a number of controls, the traditional design-time integration system conflicts and presents some issues.

As a result, we had to move the binaries from the Bin directory of the toolkit installation folder into a new Testing directory.

So the two test framework assemblies (Microsoft.Silverlight.Testing and Microsoft.VisualStudio.QualityTools.UnitTesting.Silverlight) have moved.

This location change could cause existing applications that reference the test assemblies to fail to compile due to the "missing" references.

If that happens, please delete the two broken references and create references to these assemblies in their new location. Everything else should continue to work as expected.

Simplified test project template

In alignment with the test project changes in Visual Studio 2010, which are more simplified, the unit test project template for Silverlight no longer includes a README.TXT file.

Known issues

Test service

I’ve received reports from a number of people about issues with the test service automation support. Some of the NDA/preview users of the framework reported issues that were corrected, but there may still be some bugs out there. I’m working to investigate and post a fix if and when I know more.

In the meantime I know that StatLight, a third party system, has been updated for the April release and is working well for automation.

Test panel and visuals

Please beware that some of your tests may need to be updated to use the new framework if your application, utility functions, or tests ever used the Application.Current.RootVisual (against the recommended pattern for interface testing).

The root visual is now the test framework application runner itself, and the tests run within the same TestPanel as before. Controls added to the test panel will not be located at the 0, 0 screen position, but likely near the bottom of the screen instead.

Hope this helps. To get started, download and install the April toolkit!

Property change notifications for multithreaded Silverlight applications

Jeff Wilcox — Fri, 02 Apr 2010 18:27:28 +0000

As I’ve been developing more complex Silverlight business applications, I’ve been increasingly relying on BackgroundWorker to offload complex calculations and operations to the background thread.

Something I didn’t have to worry about in the typical user interface thread-only implementation of my app was which thread change notifications fire on.

Here’s a typical scenario:

You have a CLR property on a data/model object in your app. In a background thread, the property is updated.
As all data and model objects should be, the type implements INotifyPropertyChanged (the data binding system relies on this to know when to update bindings).
The property changed event is fired, and listeners react to the change, including the data binding system.
The data binding system throws an invalid cross thread exception, since all UI operations, including handing off the binding changes, need to happen on the UI thread (but it’s happening on a background thread)

So what you really need to do is funnel those change notifications back to always happen on the user interface thread – that’s what makes the most sense given the data binding requirement.

By using a dispatcher, which can accept a BeginInvoke for that other thread, it will all just work and binding will move along happily:

This scenario is ripe for a few helper classes that I’m open to receiving feedback on. Hope you agree with my approach of using a ‘smart dispatcher’.

One Dispatcher to rule them all

The only thing you need to fire an Action on the primary UI thread is a reference to a Dispatcher instance. Unfortunately this isn’t something you can request from a background thread – you need to have the instance already stored away in most cases.

As a result, I’ve a static helper class and in it, I try and make sure that there is an instance stored before any of my data binding or model code is used.

Though I could have used SynchronizationContext instead, Dispatcher is a little easier to use, and better suited to WPF and Silverlight apps.

In my App.xaml.cs, I add a line that calls Initialize on my class. This is to make sure that there is always an available dispatcher for other threads to get access to:

public App()
{
    this.Startup += this.Application_Startup;
    this.Exit += this.Application_Exit;
    this.UnhandledException += this.Application_UnhandledException;

    SmartDispatcher.Initialize(Deployment.Current.Dispatcher);

    InitializeComponent();
}

If you didn’t want to have to add this code to initialization, my implementation of a dispatcher helper class falls back to trying to grab the dispatcher from the root visual – but this won’t work in all scenarios, so I prefer the above. One more thing to remember however.

Being smart about using the dispatcher

It’s easy enough to replace all event firings for property changes to go through the dispatcher. However, this will reduce performance some; instead of the call being made immediately, it’s made at a later time.

There is a hidden method called CheckAccess on Dispatcher that returns true if you are on the same thread that the Dispatcher was first created in. By checking with it before making a call, we can make a better perf choice:

If CheckAccess is true and we’re on the UI thread, just go ahead and directly invoke the Action.
Else, BeginInvoke with the Dispatcher that will take care of getting it done on the UI thread later.

I’ve also done some optimization to try and ensure that the design-time experience at least stays consistent. In general you shouldn’t have background operations ever occurring in a design-time scenario.

The static helper class I’ve created is called SmartDispatcher and simplifies all of this logic.

So here’s my smart dispatcher implementation:

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

using System.ComponentModel;

namespace System.Windows.Threading
{
    /// 
    /// A smart dispatcher system for routing actions to the user interface
    /// thread.
    /// 
    public static class SmartDispatcher
    {
        /// 
        /// A single Dispatcher instance to marshall actions to the user
        /// interface thread.
        /// 
        private static Dispatcher _instance;

        /// 
        /// Backing field for a value indicating whether this is a design-time
        /// environment.
        /// 
        private static bool? _designer;

        /// 
        /// Requires an instance and attempts to find a Dispatcher if one has
        /// not yet been set.
        /// 
        private static void RequireInstance()
        {
            if (_designer == null)
            {
                _designer = DesignerProperties.IsInDesignTool;
            }

            // Design-time is more of a no-op, won't be able to resolve the
            // dispatcher if it isn't already set in these situations.
            if (_designer == true)
            {
                return;
            }

            // Attempt to use the RootVisual of the plugin to retrieve a
            // dispatcher instance. This call will only succeed if the current
            // thread is the UI thread.
            try
            {
                _instance = Application.Current.RootVisual.Dispatcher;
            }
            catch (Exception e)
            {
                throw new InvalidOperationException("The first time SmartDispatcher is used must be from a user interface thread. Consider having the application call Initialize, with or without an instance.", e);
            }

            if (_instance == null)
            {
                throw new InvalidOperationException("Unable to find a suitable Dispatcher instance.");
            }
        }

        /// 
        /// Initializes the SmartDispatcher system, attempting to use the
        /// RootVisual of the plugin to retrieve a Dispatcher instance.
        /// 
        public static void Initialize()
        {
            if (_instance == null)
            {
                RequireInstance();
            }
        }

        /// 
        /// Initializes the SmartDispatcher system with the dispatcher
        /// instance.
        /// 
        /// The dispatcher instance.
        public static void Initialize(Dispatcher dispatcher)
        {
            if (dispatcher == null)
            {
                throw new ArgumentNullException("dispatcher");
            }

            _instance = dispatcher;

            if (_designer == null)
            {
                _designer = DesignerProperties.IsInDesignTool;
            }
        }

        /// 
        ///
        /// 
        /// 
        public static bool CheckAccess()
        {
            if (_instance == null)
            {
                RequireInstance();
            }

            return _instance.CheckAccess();
        }

        /// 
        /// Executes the specified delegate asynchronously on the user interface
        /// thread. If the current thread is the user interface thread, the
        /// dispatcher if not used and the operation happens immediately.
        /// 
        /// A delegate to a method that takes no arguments and
        /// does not return a value, which is either pushed onto the Dispatcher
        /// event queue or immediately run, depending on the current thread.
        public static void BeginInvoke(Action a)
        {
            if (_instance == null)
            {
                RequireInstance();
            }

            // If the current thread is the user interface thread, skip the
            // dispatcher and directly invoke the Action.
            if (_instance.CheckAccess() || _designer == true)
            {
                a();
            }
            else
            {
                _instance.BeginInvoke(a);
            }
        }
    }
}

A property change base class

Next up, instead of having to manually wire up the INotifyPropertyChanged interface in all my data classes, I prefer to derive from a common base class, PropertyChangedBase, that has logic in it to use my smart dispatcher.

This base class:

Has a protected NotifyPropertyChanged method that does all the real work
Statically stores created event arguments to improve performance over time (only one PropertyChangedEventArgs instance is required per property name in the application’s lifetime)
Uses SmartDispatcher to use a dispatcher only if not running on the user interface thread, otherwise directly invokes the property change handler.

// (c) Copyright Microsoft Corporation.
// This source is subject to the Microsoft Public License (Ms-PL).
// Please see http://go.microsoft.com/fwlink/?LinkID=131993 for details.
// All other rights reserved.

using System;
using System.Collections.Generic;
using System.Windows.Threading;

namespace System.ComponentModel
{
    /// 
    /// A base class for data objects that implement the property changed
    /// interface, offering data binding and change notifications.
    /// 
    public class PropertyChangedBase : INotifyPropertyChanged
    {
        /// 
        /// A static set of argument instances, one per property name.
        /// 
        private static Dictionary _argumentInstances = new Dictionary();

        /// 
        /// The property changed event.
        /// 
        public event PropertyChangedEventHandler PropertyChanged;

        /// 
        /// Notify any listeners that the property value has changed.
        /// 
        /// The property name.
        protected void NotifyPropertyChanged(string propertyName)
        {
            if (string.IsNullOrEmpty(propertyName))
            {
                throw new ArgumentException("PropertyName cannot be empty or null.");
            }

            PropertyChangedEventHandler handler = PropertyChanged;
            if (handler != null)
            {
                PropertyChangedEventArgs args;
                if (!_argumentInstances.TryGetValue(propertyName, out args))
                {
                    args = new PropertyChangedEventArgs(propertyName);
                    _argumentInstances[propertyName] = args;
                }

                // Fire the change event. The smart dispatcher will directly
                // invoke the handler if this change happened on the UI thread,
                // otherwise it is sent to the proper dispatcher.
                SmartDispatcher.BeginInvoke(delegate
                {
                    handler(this, args);
                });
            }
        }
    }
}

Putting it all together

To use this in your own application, you take your model/data classes and derive from PropertyChangedBase. Then, in CLR setters, always call NotifyPropertyChanged:

public class SampleData : PropertyChangedBase
{
    private string _someText;
    public string SomeText
    {
        get { return _someText; }
        set
        {
            _someText = value;
            NotifyPropertyChanged("SomeText");
        }
    }
}

Grab the code

I’ve decided to place these classes inside their appropriate system namespaces: System.Windows.Threading for the smart dispatcher, and System.ComponentModel for the PropertyChangedBase. Hope that isn’t too offensive.

Here are the files for download as well:

Hope this helps. Let me know what you think.

Template parts and custom controls (quick tip)

Jeff Wilcox — Fri, 02 Apr 2010 00:40:57 +0000

Here’s a few simple tips and recommendations when developing custom Silverlight controls, as it relates to template parts.

What’s with all the control development tips?

We’re looking at the best way to share a lot of the ‘black magic’ of control development with the community, and will have details on that another way – today so much of this information is hidden away in blog posts like this one.

Hopefully we’ll have a whitepaper at some point.

What are template parts?

Visualizing a control and it’s expected template: “MyControl” has a template part called Button, of type ButtonBase. And although it also may contain a text box, no events from the text box are used. Instead, just a template binding to the Text property.

This control has 1 template part: Button, not two. Don’t be tempted to have a text box template part!

Do you need template parts or not?

It’s important to minimize the number of template parts in a control to reduce complexity. Over-engineering controls leads to reduced code quality, expensive control maintenance, and increased testing cost.

If you can expose dependency properties and template bind into those properties from controls in the template, there is absolutely no reason to have parts present.

If you need to hook up to events of anything in the template, it’s likely that you will need to have a part for that sub control.

Choose wisely.

Use constants for the names

To prevent potential spelling errors or simple mistakes, it’s a good idea to not hard-code the template part name anywhere in your control.

Instead, add a constant string to the top of the file with the part name. You can then refer to it in the OnApplyTemplate method, the template part attribute, and anywhere else it is needed.

The constant can be protected if a subclass may want to reuse the name.

private const string PartButtonName = "Button";

Store parts as private fields in your class

Template parts are not designed to always be inherited by any subclasses. Though the subclasses are welcome to use the same parts, they should not expect to just use the base classes: they need to use OnApplyTemplate to also grab instances of the parts.

So do use private fields to store the parts in the OnApplyTemplate method:

private ButtonBase _button;

Detach any existing event handlers in OnApplyTemplate

Controls can be restyled and retemplated as a result. Make sure to detach any event handlers from previous template parts before adding new handlers.

Here’s the typical pattern for that:

public override void OnApplyTemplate()
{
    base.OnApplyTemplate();
    if (_button != null)
    {
        _button.Click -= OnButtonClick;
    }

    _button = GetTemplateChild(PartButtonName) as ButtonBase;

    if (_button != null)
    {
        _button.Click += OnButtonClick;
    }
}

Don’t assume template parts exist

Whenever using template parts in your code, you should not assume that they exist. Always check for null, and unless a significant reason exists for requiring their presence, never throw an error in this condition.

Often code in the class relating to states and properties will execute long before the template is applied, yielding no template part instances early on.

if (_button != null)
{
   // Do something with the button
}

Mark controls with template part attributes

Design surfaces like Expression Blend expect that controls are marked with the template part attributes. These are required to provide helpful tooling for editing templates.

Make sure to use the constant template part name that you created a few tips ago:

[TemplatePart(Name = PartButtonName, Type = typeof(ButtonBase))]
public partial class MyControl : ContentControl
{
}

Template parts don’t necessarily inherit from their base class

It’s possible to have different template parts at each level of a control’s hierarchy. It’s even possible that subclasses may not want to use a template of a base class.

As a result, never provide template parts as public or protected properties on your controls. If subclasses want them, they can ask for them.

This is another reason it’s important to quietly check template parts for null, they may not be defined in base classes.

You should define template part attributes on every subclasses where expected. They do not inherit.

Hope this helps.

Other tips

David Anson has been furiously writing tips as well as we all have hallway conversations on control development: Check out:

Jeff Wilcox » Silverlight

Exploring List capacities and growth on the Windows Phone

Constructed capacity is ZERO

First item brings the capacity to 4 items

Capacity + 1 grows the capacity exponentially

Clipping the capacity back

Initializing to a set size

Windows Phone performance progress bar update: part 2, remember to turn IsIndeterminate off when not needed!

1: Use PerformanceProgressBar over the built-in ProgressBar style

2: Turn off IsIndeterminate when not needed

Blend tip: finding default styles using “Edit a Copy”

Getting started

Add the control that you’d like the template or style of

Use the Edit Template menu right-click option

View the XAML

Note: Nested styles and templates

Note: Windows Phone developer tools theme XAML

Looking ahead: Panorama and Pivot controls for Windows Phone developers

Learning about the native experience

Key Features

Panorama

Panorama XAML

About wide horizontal sections

Panorama APIs

Microsoft.Phone.Controls.Panorama

Dependency Properties

Events

Microsoft.Phone.Controls.PanoramaItem

Dependency Properties

Pivot control

Pivot XAML

Pivot APIs

Microsoft.Phone.Controls.Pivot

Dependency Properties

Events

Microsoft.Phone.Controls.PivotItem

Visual Studio & Expression Blend Tooling

Start with a complete application template

Add New Pages

Blend Assets

Easy property editing

Right-click, add new panorama item or pivot item

Other notes

Exposing scrolling data

Items control API

Both controls

Differences

Migration

Stay tuned!

TiltContentControl for Windows Phone

Introducing Luke’s TiltContentControl

ContentControl vs Attached Property

Adding the control to your project

How to use the control within your project

Creating and using a custom easing function

Quick perf lesson #1: Avoid custom easing functions as they have a negative performance implication

Quick perf lesson #2: Store a single static instance of property paths when creating animations in code

Does this tilt exactly match the OS?

Workaround note for beta tools developers

Full implementation of TiltContentControl.cs

Namespace: Microsoft.Phone.Controls.Unofficial

Creating high performance Windows Phone apps – THE WHITEPAPER

A high performance ProgressBar for Windows Phone

8/17/10 Update

The original post follows:

Using the PerformanceProgressBar in your app

Get the code

Add the PerformanceProgressBar style

Add this alternate ProgressBar control style everywhere

The back story

Why Slider is in the template

Animating the Slider::Value property means the animation happens on the UI thread (not good!)

What needs to change in ProgressBar? Should we build our own?

Why can’t MSFT update the progress bar in the platform?

Shouldn’t everything just be fast and have great performance anyway?

What’s this RelativeAnimatingContentControl I added to my project?

Why’s the control in the Microsoft.Phone.Controls.Unsupported namespace?

What changed in the PerformanceProgressBar style

Feedback

Frame rate counters in Windows Phone