The blog of dlaa.me

This isn't my first time discussing animating device orientation changes, so I won't spend a lot of time explaining the motivation. Here's where things left off last time:

For "in your face" transitions, there's AnimateOrientationChangesFrame which animates the rotation interactively (but might get bogged down by complex layouts). For more subtle transitions that perform smoothly regardless of how complex the page layout is, there's FadeOrientationChangesFrame which fades between the before/after layouts. Both classes have the same API and both are used in the same manner - it's just a matter of choosing the right one for your scenario.

 

The purpose of this post is to announce a new class, HybridOrientationChangesFrame, which is meant to combine the best parts of the two existing classes!

By coincidence, René Schulte and Steve Starck independently contacted me last week to ask about implementing something that unified AnimateOrientationChangesFrame and FadeOrientationChangesFrame: code that animated the rotation between the "before" and "after" states - but faded between them instead of morphing from one shape into the other. The idea behind their request is to get some of the same "Ooh, the application is turning!" visual appeal of AnimateOrientationChangesFrame without the undesirable performance implications for complex layouts. Because the "before" and "after" states don't change size in the proposed scenario, the entire animation can be done on the composition (render) thread! This same visual effect is implemented by some of the core Windows Phone 7 applications - so now it's easy to match that effect in your own applications with HybridOrientationChangesFrame!

While all three of my classes continue to share the same API, the implementation of HybridOrientationChangesFrame is much closer to FadeOrientationChangesFrame than AnimateOrientationChangesFrame. The main difference is that HybridOrientationChangesFrame runs four simultaneous Timelines instead of just one. However, that's not a cause for concern because they're all part of the same Storyboard and the right kind to run on the composition thread (specifically: DoubleAnimations of UIElement.Opacity and RotateTransform.Angle). So although there's a little more activity going on here, there's no need to run expensive (UI thread-bound) layout passes or anything like that. Consequently, HybridOrientationChangesFrame (just like FadeOrientationChangesFrame) should run smoothly even for applications with complex page layouts.

It's good to have choices in life - and now you have 50% more choice when it comes to handling Windows Phone 7 orientation changes! :)

 

[Click here to download the DynamicOrientationChanges sample and pre-compiled assembly for the Windows Phone 7 platform.]

 

 

The steps for adding a rotation/fade/hybrid animation to a new application remain the same:

1. Enable support for orientation changes by making the following change to the XAML for the relevant PhoneApplicationPages (note that rotation is not enabled by default for new pages):

   SupportedOrientations="Portrait"

   SupportedOrientations="PortraitOrLandscape"

2. Verify (by running in the emulator or on the device) the pages you expect to support rotation really do - if things aren't rotating at this point, trying to animate the rotations won't help. :)

3. Add the AnimateOrientationChangesFrame.cs or FadeOrientationChangesFrame.cs or HybridOrientationChangesFrame.cs source code file from the sample to your project/solution.

   -OR-

   Add a reference to the pre-compiled DynamicOrientationChanges.dll assembly from the sample download to your project/solution.

4. Open App.xaml.cs and change the RootFrame initialization in the InitializePhoneApplication method (you may need to expand the Phone application initialization region at the bottom):

   RootFrame = new PhoneApplicationFrame();

   RootFrame = new Delay.AnimateOrientationChangesFrame();

   -OR-

   RootFrame = new Delay.FadeOrientationChangesFrame();

   -OR-

   RootFrame = new Delay.HybridOrientationChangesFrame();

5. Done; rotations will now be animated! To customize the animation, use the Duration, EasingFunction, and IsAnimationEnabled properties which are all present and continue to work as outlined in the original post.

 

HtmlTextBlock is a control I wrote way back in 2007 to enable the display of simple HTML markup by the Silverlight (1.1 Alpha!) platform without needing to translate it to XAML first. HtmlTextBlock was intended more as a proof-of-concept than anything else, but it seems to have satisfied a fairly common customer need and I've heard from lots of customers who are using it! But my last update was in 2008 and I'd kind of forgotten about this project since then...

Until - out of the blue - Morten Nielsen (@SharpGIS) contacted me a few days ago to let me know about an update he'd done to HtmlTextBlock to use Silverlight 4's RichTextBox to address some of the limitations HtmlTextBlock had by virtue of its very simple beginnings. I don't want to steal his thunder, so please have a look at Morten's post for the details and the new download!

Thanks a lot, Morten! :)

In my previous post announcing the release of the Windows Phone Toolkit, I explained the motivation for the PhoneApplicationPage-based design of the DatePicker and TimePicker controls. Though justified, the current implementation is fairly unusual and has the potential to trip people up if they're not ready for it. So I highly recommend reading the details at the end of that post if you're using DatePicker or TimePicker.

[Waits patiently...]

Okay, if you read the notes, then you understand what we've done and why. And while I'm happy to discuss the pros and cons of the current implementation, that's what we've got for now and I'm going to spend a little time highlighting its extensibility!

 

As with the rest of the Phone Toolkit, our primary goal was to make it easy for developers to match the core Windows Phone 7 experience in their own applications. Toward that end, adding an instance of DatePicker or TimePicker to a page gives the same "small button expands to full-page date/time picker with infinite scrolly thingies" experience that's found in the core Settings, Calendar, and Alarms applications. But sometimes you want to do things a little differently, and maybe you've got a date/time picking interface in mind that's more relevant to your scenario...

 

Aside: If what you want to do is change the format used to display the date/time on the face of the initial "button", then all you need to do is set the ValueStringFormat property to the standard date and time format string or custom date and time format string of your choice!

But because format strings include "{" and "}", they're a little tricky to code in XAML; you need to escape the special characters. here's an example of what this looks like in its simplest form: ValueStringFormat="{}{0:d}"

And here are a few practical examples (using the culture settings for USA):

Description	XAML	Sample
Short date format (DatePicker default)	"{}{0:d}"	9/20/2010
Short time format (TimePicker default)	"{}{0:t}"	4:00 PM
Long date format	"{}{0:D}"	Monday, September 20, 2010
Long time format	"{}{0:T}"	4:00:00 PM
Explicit month/day/year format	"{}{0:MM-dd-yyyy}"	09-20-2010
Explicit 24-hour time format with text	"{}The 24-hour time is {0:HH:mm}."	The 24-hour time is 16:00.

 

Customizing the full-screen picker page is as simple as setting the DatePicker.PickerPageUri or TimePicker.PickerPageUri property to point to a PhoneApplicationPage that implements the IDateTimePickerPage interface. The PickerPageUri property uses the standard assembly-relative syntax ("/assemblyShortName;component/resourceLocation"), so it should be familiar to most folks. The IDateTimePickerPage interface is a new interface, but I think you'll agree it's pretty basic:

namespace Microsoft.Phone.Controls.Primitives
{
    /// <summary>
    /// Represents an interface for DatePicker/TimePicker to use for communicating with a picker page.
    /// </summary>
    public interface IDateTimePickerPage
    {
        /// <summary>
        /// Gets or sets the DateTime to show in the picker page and to set when the user makes a selection.
        /// </summary>
        DateTime? Value { get; set; }
    }
}

 

When it's time to display the picker page, DatePicker and TimePicker navigate to the page specified by PickerPageUri via the NavigationService.Navigate("...") method, wait for the page to load, get a reference to its IDateTimePickerPage interface, and set its Value property to the starting DateTime. After that, the custom picker page is in complete control and can display any UI it wants. When the custom picker is done (either because the user picked a date/time or because the user cancelled the operation), the picker should set its Value property to the selected date/time (or null if cancelled) and then call NavigationService.GoBack to return to the previous page. DatePicker and TimePicker automatically detect this, update their own Value property (which automatically updates their UI), and fire their ValueChanged event.

In some ways, it's actually kind of elegant! :) And the fact that the picker is entirely implemented by its own PhoneApplicationPage makes it really easy to work with at design-time in Visual Studio and Blend.

 

To help illustrate the process, I created a sample application that uses custom pickers for DatePicker and TimePicker which let the user pick times relative to the current time:

The sample application shows the current date and time because what the emulator reports isn't always the same as what the host operating system reports! In my experience, it's often an hour or more off - so please keep in mind that the times used by the sample are relative to emulator time!

 

Here's the XAML for the main page that hosts the DatePicker and TimePicker controls:

<toolkit:DatePicker
    Value="10/10/2010"
    Header="Custom Date Picker Page"
    PickerPageUri="/CustomDateTimePickerPage;component/CustomDatePickerPage.xaml"/>

<toolkit:TimePicker
    Value="{x:Null}"
    Header="Custom Time Picker Page"
    PickerPageUri="/CustomDateTimePickerPage;component/CustomTimePickerPage.xaml"/>

Aside: Just for fun, I've explicitly set the Value properties here. Although the controls' default behavior of using the current date/time is likely to be what you want most of the time, applications are free to override the initial date/time (as DatePicker does above) or to provide a blank starting value (as TimePicker does with the x:Null markup extension).

 

The implementation of the custom PhoneApplicationPage implementation is so basic, I'm going to show the complete date picker here! (The custom time picker implementation is nearly identical.) I've highlighted the particularly interesting bits, but by now they should be familiar.

First the XAML, then the code:

<phone:PhoneApplicationPage
    x:Class="CustomDateTimePickerPage.CustomDatePickerPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    FontFamily="{StaticResource PhoneFontFamilyNormal}"
    FontSize="{StaticResource PhoneFontSizeNormal}"
    Foreground="{StaticResource PhoneForegroundBrush}"
    SupportedOrientations="PortraitOrLandscape" Orientation="Portrait"
    mc:Ignorable="d" d:DesignHeight="800" d:DesignWidth="480">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>

        <TextBlock
            Text="CHOOSE CUSTOM DATE"
            Margin="12"
            FontWeight="Bold"/>

        <StackPanel
            Grid.Row="1"
            VerticalAlignment="Center">
            <Button Content="Tomorrow" Click="TomorrowButtonClick"/>
            <Button Content="Next Week" Click="NextWeekButtonClick"/>
            <Button Content="Next Month" Click="NextMonthButtonClick"/>
            <Button Content="[Cancel]" Click="CancelButtonClick"/>
        </StackPanel>
    </Grid>

</phone:PhoneApplicationPage>

public partial class CustomDatePickerPage : PhoneApplicationPage, IDateTimePickerPage
{
    /// <summary>
    /// Gets or sets the DateTime value for the IDateTimePickerPage interface.
    /// </summary>
    public DateTime? Value { get; set; }

    public CustomDatePickerPage()
    {
        InitializeComponent();
    }

    private void TomorrowButtonClick(object sender, RoutedEventArgs e)
    {
        ChooseDate(DateTime.Now.AddDays(1));
    }

    private void NextWeekButtonClick(object sender, RoutedEventArgs e)
    {
        ChooseDate(DateTime.Now.AddDays(7));
    }

    private void NextMonthButtonClick(object sender, RoutedEventArgs e)
    {
        ChooseDate(DateTime.Now.AddMonths(1));
    }

    private void ChooseDate(DateTime date)
    {
        // Commit date and close picker
        Value = date;
        NavigationService.GoBack();
    }

    private void CancelButtonClick(object sender, RoutedEventArgs e)
    {
        // Cancel selection and close picker
        Value = null;
        NavigationService.GoBack();
    }
}

 

As you can see, creating a custom picker page for DatePicker and TimePicker is really easy! As long as you play by a few basic rules, you have complete freedom to style the entire picker experience in a self-contained, interactive, designer-friendly way. It's kind of like re-Templating - but easier and more flexible - in a weird kind of way!

 

[Click here to download the complete source code for the CustomDateTimePickerPage sample application.]

 

Now get to it - I'm looking forward to seeing the kinds of custom picker experiences you all come up with! :)

If you happen to have 11 minutes, 2 seconds lying around and don't know what to do with yourself, you might consider watching or listening to episode 5 of the Inside Windows Phone show on Channel 9. Of course, I'm a bit biased - this episode features Dave Relyea and I talking about the new controls in the Silverlight for Windows Phone Toolkit we just released. Dave and I were two of the four people who created the Phone Toolkit (the others being Scott Morrison and Will Faught) and were fortunate to be invited by Jaime Rodriguez to talk about it on Channel 9. (If you've never seen a Channel 9 video, it's informal and off-the-cuff. No script and no re-takes - at least for us!)

 

Without further ado, here's Inside Windows Phone #05:Windows Phone Silverlight Toolkit:

 

If you enjoyed that, you might also enjoy Inside Windows Phone #06: Panorama and Pivot are in the house! Woohoo!! which covers the new Windows Phone Panorama and Pivot controls. This was another project Dave Relyea, Scott Morrison, and I were involved in - along with Jeff Wilcox (who's featured in the video).

Thanks a lot to Jaime and the Channel 9 folks for creating these videos. I hope you find them useful - or at least entertaining! :)

Today marks the official release of the Windows Phone Developer Tools. This free download enables anyone to create .NET applications for the Windows Phone 7 platform using the Silverlight framework (for traditional applications) or the XNA framework (for games). The Windows Phone 7 application development experience is fully integrated with Visual Studio 2010 and Blend 4 and also includes an emulator for running and testing applications without having a phone. It's really cool stuff, and I encourage everyone to learn more about Windows Phone 7 development!

Congratulations to the Windows Phone 7 team on their accomplishment!

 

To celebrate, there's a new download for the Silverlight Toolkit CodePlex project: the Silverlight for Windows Phone Toolkit September 2010 release! Yes, that's right - in addition to providing controls for Silverlight developers targeting the desktop, we're also providing controls for Silverlight developers targeting Windows Phone 7! As you might guess, the Windows Phone Toolkit is a lot like the Silverlight Toolkit: the goal is still to provide a set of controls that complement the platform's core offering and help developers/designers create more compelling, more platform-consistent user experiences simply and easily. Because we focus on writing solid, reusable controls that address common scenarios, you are free to focus on delivering an engaging, compelling application to your customers!

As with the Silverlight Toolkit, the Windows Phone Toolkit comes with full source code (under the permissive OSI-approved Ms-PL license) to help people learn the techniques behind developing rich, platform-consistent controls, to see how we solved a particular problem, or to make tweaks and improvements to the controls themselves! The idea is to publish the Windows Phone Toolkit every few months or so; each release will include new controls, improvements to existing controls, and fixes for any bugs people run into. If you have a suggestion for something we should add or change, please search for that issue in the CodePlex issue tracker and vote for it (or create a new issue if your idea is unique). We pay attention to the number of votes an issue has when prioritizing our efforts - it helps ensure we're delivering what the community wants!

 

Okay, after all that intro and background, you're probably wondering what's actually in the Phone Toolkit... :)

 

What's in the Phone Toolkit?

ContextMenu and ContextMenuService

In desktop applications, ContextMenu is handy because it lets the second mouse button perform additional, contextually-relevant tasks; but on the phone, it's practically a requirement! Phone-sized UIs need to use every pixel to its fullest advantage, so being able to hide secondary commands behind a tap+hold gesture is a great way to keep the interface clean and easy to read.

The Windows Phone Toolkit's ContextMenu control is a direct port of the Silverlight 4 Toolkit's ContextMenu (read more about what it does and how it works here) with additional Windows Phone-specific functionality added on top. So the Phone ContextMenu uses the same, great 100% Silverlight- and WPF-compatible ItemsControl-based API you know and love - plus it looks good on the phone and behaves just like the system's ContextMenu does! Which means ContextMenu (along with its helper ContextMenuService) is simple to use and makes it easy for Windows Phone applications to maintain platform-consistent appearance and behavior. (And for advanced scenarios, ContextMenu supports the ICommand interface, data-binding (of and to) items, Separator, and more!)

Here's the XAML for the example above:

<Border
    Background="{StaticResource PhoneChromeBrush}"
    Padding="20">
    <toolkit:ContextMenuService.ContextMenu>
        <toolkit:ContextMenu>
            <toolkit:MenuItem
                Header="gray text"
                Click="MenuGrayTextClick"/>
            <toolkit:MenuItem
                Header="normal text"
                Click="MenuNormalTextClick"/>
        </toolkit:ContextMenu>
    </toolkit:ContextMenuService.ContextMenu>
    <TextBlock
        x:Name="MenuTextBlock"
        Text="Tap and hold for ContextMenu"
        HorizontalAlignment="Center"/>
</Border>

 

DatePicker and TimePicker

Windows Phone 7 includes a cool, distinctive UI for choosing dates and times: three vertical spinners create a fun "endless looping" experience that people really enjoy using. The Phone Toolkit's DatePicker and TimePicker controls implement the exact same experience as the core controls, so it's easy to add date and time selection to your own application!

What's more, these controls are both culture-aware and automatically configure themselves according to the settings on the user's phone (ex: d/m/y vs. m/d/y date formats and 12- vs. 24-hour time format). The API for DatePicker and TimePicker will be familiar to anyone who's used similar "picker" controls in the past. The Header convenience property simplifies the task of labeling either control - in a platform-consistent font and style!

Here's the XAML for the example above and to the right:

<toolkit:DatePicker
    Header="Date"
    Value="9/16/2010"
    ValueChanged="DatePickerValueChanged"/>
<toolkit:TimePicker
    Header="Time"
    Value="12:34 pm"
    ValueChanged="TimePickerValueChanged"/>

 

ToggleSwitch

The Windows Phone UI for toggling settings on and off will be immediately familiar to anyone who's used a light switch (or an iDevice). Because there are subtleties to the core controls that are tricky to get right, the Toolkit includes the ToggleSwitch control! Continuing the theme of "make it easy to match the core behavior", ToggleSwitch looks, feels, and acts just like Windows Phone users will expect - including supporting flicks and swipes. In addition to subclassing ToggleButton for consistency and usability, ToggleSwitch supports the Header convenience property to make it easy to create properly-spaced settings pages. And if the need arises, you can also provide custom Content or pull the ToggleSwitchButton primitive control out and use it directly!

Here's the XAML for the example above:

<toolkit:ToggleSwitch
    Header="Some feature"
    IsChecked="true"
    Checked="ToggleSwitchChanged"
    Unchecked="ToggleSwitchChanged"/>

 

GestureListener and GestureService

Touch interfaces are a lot more interactive and engaging than the conventional mouse+keyboard UI most people are used to. One of the neatest things about touch UIs are their ability to translate natural human gestures into meaningful commands. Taking good advantage of touch and gestures can significantly improve the user experience and really help an application stand out from the crowd.

To make gestures easy to work with, the Phone Toolkit includes the GestureService and GestureListener classes which provide events for the following gestures: tap, double-tap, hold, flick, drag (started/delta/completed), and pinch (started/delta/completed). All these gestures respect the relevant system parameters (ex: movement threshold, input timing, etc.), so applications that use GestureListener feel familiar and natural. All the developer needs to do is associate a GestureListener with the element(s) of interest and handle the corresponding gesture event(s) as they show up!

For more background on gestures, here's a nice, easy to visualize overview for Windows 7 (not identical, but close) and here's a detailed document specific to windows Phone 7.

Here's the XAML for the example above (note that typical applications will only hook up to the event(s) they care about):

<Border
    Background="{StaticResource PhoneChromeBrush}"
    Padding="40">
    <toolkit:GestureService.GestureListener>
        <toolkit:GestureListener
            Tap="GestureListenerTap"
            DoubleTap="GestureListenerDoubleTap"
            Hold="GestureListenerHold"
            Flick="GestureListenerFlick"
            DragStarted="GestureListenerDragStarted"
            DragDelta="GestureListenerDragDelta"
            DragCompleted="GestureListenerDragCompleted"
            PinchStarted="GestureListenerPinchStarted"
            PinchDelta="GestureListenerPinchDelta"
            PinchCompleted="GestureListenerPinchCompleted"/>
    </toolkit:GestureService.GestureListener>
    <TextBlock
        x:Name="GestureTextBlock"
        Text="Perform any gesture here"
        HorizontalAlignment="Center"/>
</Border>

 

WrapPanel

It may not be the sexiest of the Panel classes, but WrapPanel is a tremendously useful layout container! Lots of Windows Phone developers have been using this control from the Silverlight 3 Toolkit (either by referencing that assembly or by copying the code into their projects), but that can be a little tricky - so we thought we'd make it super easy by including WrapPanel in the Phone Toolkit! WrapPanel's "put as much stuff on a line as fits, then wrap to the next line" approach works particularly well on the phone - especially for scenarios where the sizes of things can vary (ex: during the transition from portrait orientation to landscape).

Here's the XAML for the example above:

<toolkit:WrapPanel>
    <Button Content="Here"/>
    <Button Content="is"/>
    <Button Content="some"/>
    <Button Content="simple"/>
    <Button Content="content"/>
    <Button Content="that"/>
    <Button Content="wraps"/>
    <Button Content="to"/>
    <Button Content="fit"/>
    <Button Content="the"/>
    <Button Content="screen"/>
</toolkit:WrapPanel>

 

[Click here to download the sample application used to create all the examples shown here.]

 

Helpful Hints for Hopeful Heroes

Here are a few tips and tidbits to help fledgling Windows Phone 7 developers make the most of the Phone Toolkit:

• The examples I show here are from my own (deliberately simple) sample application, but there's also a more comprehensive sample application that shows off more sophisticated scenarios. The complete source code for the entire Phone Toolkit (including the sample application) can be downloaded from the CodePlex release page or the CodePlex source code page or by using any of the supported version control system clients (ex: TFS, SVN, etc.).

• Some (but not all) of the ContextMenus used by the core phone applications get a little fancy when they show the menu: they shrink the UI of the rest of the application in the background. Because we strive to help developers create consistent applications, the Toolkit's ContextMenu does this by default as well.

  But because it's not part of the application itself, our ContextMenu's behavior needs to be as self-contained as possible - which means it can not modify the existing visuals in order to create this effect. (Otherwise it might make an unexpected change that crashes the developer's application!) Therefore, the "shrink" effect is implemented by capturing a "background" screen shot of the entire application, layering it over an opaque PhoneBackgroundBrush layer to avoid transparent areas leaking through, creating a "active element" screen shot capture of just the element that was tap+held, layering this over a correspondingly-sized opaque PhoneBackgroundBrush layer (to avoid transparency issues again), creating a "menu" layer for the actual menu items, layering everything over the running application by putting it in a Popup, and finally animating the scale of the "background" layers. Whew - if that sounds like a lot of effort, it is... :)

  The good news is this works pretty well in practice and duplicates the core effect fairly authentically - the less good news is that certain page designs poke little holes in the sleight-of-hand ContextMenu is doing. In many cases, such issues can be resolved by modifying the target element (the one to which the ContextMenu is attached) to have a non-transparent background. (ContextMenu's PhoneBackgroundBrush guess is the best it can do, but the application developer can sometimes do better.)

  But if you still can't get the effect you're looking for - or if you just don't like the default "shrink and grow" behavior (the core applications don't use it everywhere, either!) - then you can set the (Phone-specific) ContextMenu.IsZoomEnabled property to false in order to disable the custom animation and get rid of all this goofy complexity. In every case I know of so far, developers who resorted to IsZoomEnabled were quite happy with the results! :)

• When you first add DatePicker or TimePicker to your application, you'll find that the "done" and "cancel" ApplicationBar icons shown when the pickers are opened are wrong. That's because the icons aren't actually being loaded - and that's because of a platform restriction. Specifically, the ApplicationBarButton.IconUri property will only load images that are part of the project and marked with Build Action=Content in the property editor. This means there's no good way for an assembly like the Phone Toolkit assembly to bundle such icons within itself (like there would be if the IconUri property supported the assembly-relative syntax "/assemblyShortName;component/resourceLocation").

  As a result, it's necessary for application developers to add these two icons to a well-known path in their project where DatePicker and TimePicker will automatically use them. For your convenience, we've bundled these two icons along with the Toolkit installer and they're already on your machine! :) To find them, open the Start Menu, expand the "Microsoft Silverlight for Windows Phone Toolkit" folder, and click on the "Binaries" item. This will open a Windows Explorer view of the install location of the Phone Toolkit (something like C:\Program Files\Microsoft SDKs\Windows Phone\v7.0\Toolkit\Sep10\Bin). The icons can be found in the "Icons" sub-folder within.

  To use these two icons in an application, right click the application's project node in the Visual Studio Solution Explorer, choose "Add", choose "New Folder", and rename it "Toolkit.Content". Then right-click on the new folder, choose "Add", choose "Existing Item...", navigate to the Phone Toolkit's install directory, select both icons, and hit "OK". Right-click each icon and change its "Build Action" to "Content"; re-run the application, and they'll show up just like you expect! (And if any of that seemed confusing, just look at how the sample application is configured - match that and you'll be fine.)

• If you already know Windows Phone 7 supports different themes ("Light" and "Dark", AKA "white background" and "black background"), you might wonder why it's not necessary to provide "Light" and "Dark" versions of each icon... Well, the platform's a little clever here - it will automatically "Light"-ify "Dark" icons when the "Light" theme is active. Therefore, all we need to do is provide is "Dark" versions of the icons - the system converts them for us!

  Note: The reverse is not true; "Light" icons will not be "Dark"-ified for you. (So it seems like maybe the "Dark" side is more powerful?)

• We've already discussed the reasons why it's good for controls to use the Popup control (because it keeps things isolated from the rest of the application), so DatePicker and TimePicker obviously use Popup too, right? Wrong! :)

  To be fair, DatePicker and TimePicker originally used a Popup for exactly those reasons. And life was good. Except when you tried to scroll the time/date spinners in the picker view... It worked okay, but the frame-rate was pretty low - almost as if the animations weren't happening on the composition (render) thread like they were supposed to... And, indeed, they weren't! It turns out the phone platform doesn't apply hardware acceleration to content in a Popup. :(

  Enough people were unhappy with the performance that DatePicker and TimePicker were modified to use a PhoneApplicationPage-based model instead. What this means is that instead of opening a Popup to hold the picker's spinner UI, these controls instead call NavigationService.Navigate("...") and point it to a Page subclass that's hosted in the same control assembly. The platform doesn't care where it loads pages from, so it happily navigates to the new Page, which then loads the spinners, which benefit from hardware acceleration, and therefore scroll smoothly!

  If this sounds like a wonderful solution, that's because it is - mostly. The big drawback to the Page-based approach is that it subtly breaks one of the guidelines of control development we discussed above: don't make changes that affect the application. In this case, if the application is already listening to the NavigationService's Navigating or Navigated events, then it will also see the "hidden" navigations that DatePicker and TimePicker are performing.

  Whether this is a problem or not depends on what the application is doing and how it's doing it. The good news is that most applications don't track navigations and won't need to worry about this at all; for applications that do track navigations, the good news is that this scenario is easy to detect. Specifically, if the object exposed by NavigationEventArgs.Content during a navigation implements IDateTimePickerPage, then the current navigation is part of DatePicker or TimePicker's behavior and should be ignored by the application. Applications that follow that simple guideline should be safe; applications that ignore it and play tricks like cancelling DatePicker and TimePicker navigations will most likely break stuff. :(

• Now that I've thoroughly scared everyone away from ever using Page-based navigations, let me back-pedal a bit and say that there are some cool things you can do with them! In particular, DatePicker and TimePicker allow you to customize their destination Page which lets you completely change the picker experience for both of them. But I've already gone on long enough here; that'll be the topic of a subsequent blog post... :)

 

We've had a lot of fun building the Silverlight for Windows Phone Toolkit - and we hope you have a lot of fun using it! Everything in the Phone Toolkit is there because there was strong customer demand. The Silverlight Toolkit team has heard you loud and clear, and we're doing our best to make your Windows Phone 7 development experience as pleasant and productive as possible!

Okay, enough chatter for now - go download the developer tools and get busy building great applications! :)

I've written about how my DynamicOrientationChanges classes improve the user experience for Windows Phone 7 applications by animating device orientation changes. For "in your face" transitions, there's AnimateOrientationChangesFrame which animates the rotation interactively (but might get bogged down by complex layouts). For more subtle transitions that perform smoothly regardless of how complex the page layout is, there's FadeOrientationChangesFrame which fades between the before/after layouts. Both classes have the same API and both are used in the same manner - it's just a matter of choosing the right one for your scenario.

 

 

The purpose of this post is to let readers know I've just updated the source code and pre-compiled DynamicOrientationChanges.dll assembly with two fixes for AnimateOrientationChangesFrame:

• On post-Beta builds of the Windows Phone 7 Tools (i.e., bits that aren't public yet, but will be soon), starting an application with AnimateOrientationChangesFrame in landscape orientation resulted in a black screen. This was due to a change in the order of startup events versus the Beta build and has been fixed so the scenario works on both the Beta and the latest (internal) phone builds. Other than upgrading to get the fix, users of AnimateOrientationChangesFrame don't need to change anything.
• In scenarios where a TextBox was present and given focus, the corresponding "pop in" of the SIP (software input panel; AKA the keyboard) would not offset the window in order to keep the TextBox visible. What goes on behind the scenes is somewhat intricate, so I was fortunate to be able to reuse the existing logic by hijacking the relevant TranslateTransform that was already responsible for this effect. Accordingly, TextBox scenarios now behave the same with AnimateOrientationChangesFrame as without - and again there's nothing application developers need to do differently.

Neither of these issues affected FadeOrientationChangesFrame (its simpler implementation is its advantage), so that code hasn't changed since last time.

Aside: I'd like to thank kind readers Mike Calligaro (yes, the same Mike who found an issue last time!) and Tonci Tonci for reporting the landscape and SIP issues (respectively) and for trying out proposed fixes to verify their correctness. (Of course, any problems are entirely my fault.)

 

[Click here to download the DynamicOrientationChanges sample and pre-compiled assembly for the Windows Phone 7 platform.]

 

 

The steps for adding a rotation/fade animation to a new application remain the same as before:

1. Enable support for orientation changes by making the following change to the XAML for the relevant PhoneApplicationPages (note that rotation is not enabled by default for new pages):

   SupportedOrientations="Portrait"

   SupportedOrientations="PortraitOrLandscape"

2. Verify (by running in the emulator or on the device) the pages you expect to support rotation really do - if things aren't rotating at this point, trying to animate the rotations won't help. :)

3. Add the AnimateOrientationChangesFrame.cs or FadeOrientationChangesFrame.cs source code file from the sample to your project/solution.

   -OR-

   Add a reference to the pre-compiled DynamicOrientationChanges.dll assembly from the sample download to your project/solution.

4. Open App.xaml.cs and change the RootFrame initialization in the InitializePhoneApplication method (you may need to expand the Phone application initialization region at the bottom):

   RootFrame = new PhoneApplicationFrame();

   RootFrame = new Delay.AnimateOrientationChangesFrame();

   -OR-

   RootFrame = new Delay.FadeOrientationChangesFrame();

5. Done; rotations will now be animated! To customize the animation, use the Duration, EasingFunction, and IsAnimationEnabled properties which are all present and continue to work as outlined in the original post.

In my previous post about how LowProfileImageLoader helps the Windows Phone 7 UI thread stay responsive by loading images in the background, I began with the following introduction:

When writing applications for small, resource-constrained scenarios, it's not always easy to balance the demands of an attractive UI with the requirements of fast, functional design. Ideally, coding things the natural way will "just work" (the so-called pit of success) - and it usually does. But for those times when things need some extra "oomph", it's nice to have options. That's what my latest project, PhonePerformance is all about: giving developers performance-focused alternatives for common Windows Phone 7 scenarios.

 

In this second post, I'll be demonstrating the use of my DeferredLoadListBox class in conjunction with the Silverlight StackPanel in order to get good performance from a scenario that's pretty common for social media applications: a scrolling list of entries with a picture and a brief bit of text. (Ex: Twitter posts, Facebook updates, blog comments, and the like.) As usual, I've written a sample application to show what I'm talking about - it displays a simple list of about 200 image+name pairs from the web (the followers of my Twitter account [you know who you are! :) ]). You can see a screen shot of the "List Scrolling" sample below:

Note: Everything in this post pertains to the latest (internal) Windows Phone 7 builds, not the public Beta bits. Although I'd expect things to work the same on the Beta build, I haven't verified that because the final bits will be released to the public on September 16th.

Additional note: My discussion assumes all testing is done on actual phone hardware. Although running the emulator on a PC is a fantastic development experience, performance of applications in the emulator can vary significantly. The emulator is great for writing new code and fixing bugs, but performance work should be done on a real phone if at all possible.

 

Okay, go ahead and run the sample and wait a moment for it to load the user list from the web (and enable those two buttons). Then choose the "default" (left) or "performance" (right) scenario and watch the behavior of the little blue dots moving across the screen as the list content populates. (I discussed the motivation behind the blue dots in the previous post - for now just remember that when the dots are flowing smoothly, life is good - and when the dots get jumpy or stop animating completely, the application is unresponsive.)

Right now, we're interested in the different load times of the two scenarios. The "performance" side uses a StackPanel to get good scroll performance, but making that switch without doing anything else is likely to increase load times versus the default VirtualizingStackPanel used by the Windows Phone ListBox (because of the loss of virtualization; more on this later). That's why the sample also uses DeferredLoadListBox - to offset the performance loss by re-introducing enough pseudo-virtualization to bring performance back up to where it was. And as the sample application shows, the load times of the two lists are very similar. (Granted, neither is instantaneous - but it's also not the case that one is consistently faster than the other.)

Now that both lists are populated, the real experiment begins: go ahead and scroll the "default" (left) list up and down and watch the item content as you do so. When scrolling at slow or moderate speeds, the movement will be smooth and the experience will be great. But once you start scrolling quickly, things begin to break down - you may start to see brief glimpses of missing items, flickering, or even black-outs...

So with that baseline experience in mind, it's time to scroll the "performance" (right) list to see how it compares. The first thing you'll probably notice is that it's slower to load the images - that's due to the use of LowProfileImageLoader and was the topic of my previous post. The next thing you'll probably notice is that the scrolling is smooth for just about any speed - and especially for content that's already been on the screen at least once! I won't claim scrolling is perfect with StackPanel and DeferredLoadListBox, but it has been my experience (and that of others) that it can be notably better than the default behavior.

 

To understand why the DeferredLoadListBox+StackPanel combination is effective, it's necessary to understand a little about how VirtualizingStackPanel works - and why that ends up being a problem in this scenario...

Pretty much every Panel implementation for Silverlight and WPF works by measuring and arranging all its elements according to various layout guidelines (ex: stack, grid, etc.). This makes it straightforward to implement a custom Panel, but it also means that all the Children must be created and live in the visual tree from the beginning. Because in the vast majority of cases there are only a handful of children (and they're all on screen anyway), this isn't a problem. However, in the "really long list" scenario, there are often only 5-10 items on the screen at a time - and a few hundred other items that aren't. VirtualizingStackPanel works in conjunction with ItemsControl and ItemContainerGenerator to create only those elements that are actually on the screen. As the user scrolls the list, VirtualizingStackPanel automatically creates containers for any items about to come into view and recycles the containers for items that just scrolled out of view. (In reality, there's usually a screen's worth of buffer on either side.) Consequently, there are two big wins with VirtualizingStackPanel: load time (by virtue of creating only a fraction of the total elements) and memory consumption (by virtue of keeping only a fraction of the total elements around at any time).

But (as sometimes happens in life) VirtualizingStackPanel's strength is also its weakness. All that container recycling and item juggling takes time to execute - and that's precious time on the UI thread that can't be spent doing other things (like updating the UI). So what seems to happen when a list is scrolling quickly enough is that the VirtualizingStackPanel falls behind more and more - until some of those containers that are scrolling into view are blank because they haven't been created or populated yet! And that's when the user sees visual glitches and rendering issues...

Therefore, the fundamental approach I've taken to avoiding problems in scenarios like this is to replace the ListBox's VirtualizingStackPanel ItemsPanel with a StackPanel. This is quite easy to do - and the StackPanel's non-virtualizing nature means that scrolling long lists will be smooth as silk. However, there are two downsides to making this switch: load time is considerably longer and memory use will be significantly higher. The increased memory consumption probably won't be an issue with small- or medium-sized lists, but it could start to be a problem for large lists containing thousands of items. But while there are options for mitigating this, that's not my objective and I won't be going into them here. (Besides, I'm not sure how practical it is for people to scroll super-long lists, anyway!)

The way I avoid longer load times is by using the DeferredLoadListBox class I wrote for just this purpose - what it does is hold off on populating off-screen containers until they're about to show up on the screen. In this manner, it restores some of the benefits of VirtualizingStackPanel by making the relevant portion of the load time (roughly) independent of the total number of items in the list. But it's important to note that DeferredLoadListBox works in one direction only! Although there's no reason it couldn't "re-virtualize" items as they scroll out of view, it specifically doesn't do so because doing (and undoing) that would consume precious CPU cycles. DeferredLoadListBox is really only about softening the blow of switching from VirtualizingStackPanel to StackPanel - it's not about trying to re-implement VirtualizingStackPanel's fundamental behavior.

So with scrolling glitches avoided and load time back to where it started, there's just one other thing slowing things down and detracting from the user experience: the jumpiness that takes place during the first full scroll of the list. What's going on there is that the first full scroll causes all those "pseudo-virtualized" containers to be created - which causes the corresponding images to be downloaded from the web. We've established that downloading images on the UI thread is bad for performance, and this is exactly the scenario I created LowProfileImageLoader for! So by throwing LowProfileImageLoader into the mix, the first full scroll stays responsive, too.

And at this point, we've arrived at the smooth, pleasing, consistent scrolling experience you get from the "List Scrolling" sample's "performance" column! Yay us! :)

 

Of course, every application - and every scenario - is different, so there's no guarantee StackPanel, DeferredLoadListBox, or LowProfileImageLoader will help all the time (or even most of the time!). But what's nice is that it's extremely easy to try them out (alone or together), so there's nothing to lose by trying them out if your scenario seems likely to benefit!

 

[Click here to download the compiled PhonePerformance assembly, sample applications, and full source code for everything.]

 

To show what I mean, here's what the default scenario looks like:

<ListBox ItemsSource="{Binding Followers}">
    <ListBox.ItemTemplate>
        <DataTemplate>
            <Grid Height="50">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="50"/>
                    <ColumnDefinition Width="10"/>
                    <ColumnDefinition/>
                </Grid.ColumnDefinitions>
                <Rectangle
                    Grid.Column="0"
                    Fill="{StaticResource PhoneChromeBrush}"/
                <Image
                    Grid.Column="0"
                    Source="{Binding ProfileImageUrl}"
                    Width="48"
                    Height="48"/>
                <TextBlock
                    Grid.Column="2"
                    Text="{Binding ScreenName}"
                    VerticalAlignment="Center"/>
            </Grid>
        </DataTemplate>
    </ListBox.ItemTemplate>
    <ListBox.ItemContainerStyle>
        <Style TargetType="ListBoxItem">
            <Setter Property="Height" Value="50"/>
        </Style>
    </ListBox.ItemContainerStyle>
</ListBox>

And here's all it takes to convert it to use StackPanel, DeferredLoadListBox, and LowProfileImageLoader:

<delay:DeferredLoadListBox ItemsSource="{Binding Followers}">
    <delay:DeferredLoadListBox.ItemTemplate>
        <DataTemplate>
            <Grid Height="50">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="50"/>
                    <ColumnDefinition Width="10"/>
                    <ColumnDefinition/>
                </Grid.ColumnDefinitions>
                <Rectangle
                    Grid.Column="0"
                    Fill="{StaticResource PhoneChromeBrush}"/>
                <Image
                    Grid.Column="0"
                    delay:LowProfileImageLoader.UriSource="{Binding ProfileImageUrl}"
                    Width="48"
                    Height="48"/>
                <TextBlock
                    Grid.Column="2"
                    Text="{Binding ScreenName}"
                    VerticalAlignment="Center"/>
            </Grid>
        </DataTemplate>
    </delay:DeferredLoadListBox.ItemTemplate>
    <delay:DeferredLoadListBox.ItemContainerStyle>
        <Style TargetType="ListBoxItem">
            <Setter Property="Height" Value="50"/>
        </Style>
    </delay:DeferredLoadListBox.ItemContainerStyle>
    <delay:DeferredLoadListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <StackPanel/>
        </ItemsPanelTemplate>
    </delay:DeferredLoadListBox.ItemsPanel>
</delay:DeferredLoadListBox>

(Don't forget to add the appropriate XMLNS to the top of the XAML file:)

xmlns:delay="clr-namespace:Delay;assembly=PhonePerformance"

 

The only thing I haven't talked about yet is the requirement that each ListBoxItem container needs to have a fixed height (via the ItemContainerStyle property; see above). This is currently necessary because it enables some optimizations in DeferredLoadListBox - however, it's important to note there's no need for all the containers to have the same fixed height - just that they all need to have a fixed height.

 

Aside: As it exists today, DeferredLoadListBox only works with vertical scrolling lists. Of course, the same concepts can be applied to horizontally scrolling lists, too, but because that's not consistent with the UI conventions of Windows Phone 7, I haven't tried to generalize the code to support both orientations. I optimized for the performance of the common scenario - but if you'd like to tweak things to support horizontal scrolling instead - or as well! - it should be fairly straightforward to do. :)

When writing applications for small, resource-constrained scenarios, it's not always easy to balance the demands of an attractive UI with the requirements of fast, functional design. Ideally, coding things the natural way will "just work" (the so-called pit of success) - and it usually does. But for those times when things need some extra "oomph", it's nice to have some options. That's what my latest project, PhonePerformance is all about: giving developers performance-focused alternatives for common Windows Phone 7 scenarios.

Note: Everything in this post pertains to the latest (internal) Windows Phone 7 builds, not the public Beta bits. Although I'd expect most everything to work on the Beta build, I haven't tested it. While that might seem a bit premature, the team has committed to releasing the final development tools on September 16th, so I'm only leading the curve a little bit here. :)

 

In this first post, I'll be demonstrating the use of the LowProfileImageLoader class. (A future post will explore the DeferredLoadListBox class which is also part of the sample download - but for now I don't want to get into what that's all about.) LowProfileImageLoader is meant to address a very specific scenario: loading lots of images from the web at the same time. This turns out to be more common than you might expect - just think about all the social media scenarios where every user has a little picture alongside their content. To help show what I'm talking about, I created the "Image Loading" sample application shown below - just run the sample, wait a little while for it to load the user list from the web (and enable the two buttons), then choose the "default" (left) or "performance" (right) scenario and watch the behavior of the little blue dots moving across the screen:

Aside: My discussion assumes all testing is done on actual phone hardware. Although running the emulator on the desktop is a fantastic development experience, performance of applications in the emulator can vary significantly. The emulator is great for writing new code and fixing bugs, but performance work should be done on a real phone if at all possible.

The ProgressBar element just below the title text has its IsIndeterminate property set to true, so it's always animating. And as others have explained, ProgressBar animates entirely on the UI thread - so while it might not be a good choice for real applications, it makes a great test tool! In this case, I'm using it to provide an indication of how overwhelmed the UI thread is - and therefore how responsive the application will be to user input or updates. If the dots are flowing smoothly, then life is good; if the dots get jumpy or stop animating completely, then the application is unresponsive.

As you can see by trying the "default" side of the sample, populating an ItemsControl having a WrapPanel (actually, it's my BalancedWrapPanel!) ItemsPanel with a couple hundred small (48x48) images from the web (the followers of my Twitter account in case you're curious) hangs the application for a noticeable amount of time. The first part of the delay is simply the cost of applying the list to the container and the second part of the delay is the cost of downloading and processing those images (mostly on the UI thread).

In an attempt to avoid this extended period of unresponsiveness, the "performance" side of the sample uses LowProfileImageLoader. Although the initial cost of binding the list is the same as before, using LowProfileImageLoader allows the UI thread to become responsive much sooner. The obvious side effect is that the images load more slowly - but the fact that those ProgressBar dots stay active the entire time demonstrates that the UI thread isn't hung like it is for the default scenario. Think about it like this: LowProfileImageLoader trades off image load speed in favor of application responsiveness.

 

The way LowProfileImageLoader works is straightforward: it creates a worker Thread and performs as much work there as possible. As soon as the SourceUri attached property is set, that Uri is enqueued for the worker thread to process. Similarly, whenever an asynchronous response comes in, that's also queued for the worker thread to process. Meanwhile, the worker thread is looking for work on any of its (three) queues and processing it in batches for efficiency. At the same time, it's making regular calls to Thread.Sleep(1) which signals to the system that other threads with work to do should get priority. (True thread priorities would be ideal, but Thread.Priority doesn't exist in Silverlight.) Finally, when it has done as much as it can off the UI thread, the worker thread calls Dispatcher.BeginInvoke to perform the final BitmapImage operations on the UI thread where they need to take place (in batches, of course). The net effect of all of this is that all the image loading LowProfileImageLoader performs occurs on a single worker thread which does its best to be efficient and stay out of the UI thread's way as much as possible - which results in a happier UI thread and a less frustrated user. :)

 

Of course, every application - and every scenario - is different, so there's no guarantee LowProfileImageLoader will help all the time (or even most of the time!). But what's nice is that it's really easy to hook up, so there's nothing to lose by trying it if your scenario seems relevant!

 

[Click here to download the compiled PhonePerformance assembly, sample applications, and full source code for everything.]

 

To make things a tad more concrete, here's what a typical scenario looks like:

<Image
    Source="{Binding ProfileImageUrl}"
    Width="24"
    Height="24"/>

And here's all it takes to convert it to use LowProfileImageLoader:

<Image
    delay:LowProfileImageLoader.UriSource="{Binding ProfileImageUrl}"
    Width="24"
    Height="24"/>

(Remember to add the appropriate XMLNS to the top of the XAML file:)

xmlns:delay="clr-namespace:Delay;assembly=PhonePerformance"

 

PS - As an added bonus, the first 500 callers will receive a free (single-purpose, super bare-bones) Twitter API! (NIH disclaimer: I know there are Twitter libraries out there, but I generally avoid third party code because I don't want to deal with licensing issues. Yeah, it's a little paranoid, but it helps me sleep better at night - and besides, this was really simple to dash off.) Operators are standing by...