The blog of dlaa.me

Posts from November 2010

Better together [DynamicOrientationChanges and TransitionFrame create a comprehensive transition experience for Windows Phone 7]

I've previously blogged about my implementation of AnimateOrientationChangesFrame, FadeOrientationChangesFrame, and HybridOrientationChangesFrame. As part of my DynamicOrientationChanges sample, these classes smoothly animate an application's layout transition as the phone orientation changes from portrait to landscape (and vice-versa).

HybridOrientationChanges sample

 

More recently, I blogged about the Windows Phone Toolkit's support for animated page transitions. The TransitionFrame class (and its helpers) work with the platform's navigation framework to animate the transitions among different pages within an application.

TransitionFrame sample

 

Though they address different scenarios, both transition helpers make it easy for developers' Silverlight applications to match the behavior of the core Windows Phone 7 applications. The obvious question is whether it's possible to use them together...

At first glance, the fact that both approaches work by directly subclassing PhoneApplicationFrame means they can't be combined as-is.

Aside: This is one of the drawbacks of subclassing as a method of adding or extending functionality in a library: you only get one chance to subclass the base class. (But because you can create as many subclasses as you want, subclassing a subclass can be an excellent alternative!)

So it has always been my hope that these two approaches could be easily combined to create an application that animates both kinds of transitions. Because the Windows Phone Toolkit's TransitionFrame class is more official, it seems appropriate to leave that one alone and try subclassing the DynamicOrientationChanges classes from TransitionFrame. Based on what I knew about both implementations, I assumed this would work, but I didn't get around to trying it before Andy Wigley contacted me with the same question! Well, Andy was brave enough to give this a go and reports that it works well - he wrote a nice summary here:

Best of breed Page rotation animations

If you're interested in combining these two scenarios, I highly recommend checking out Andy's post - he's made the change easy to understand and the steps are easy to follow!

Thanks, Andy! :)

 

PS - If others have success merging the two transition animation implementations, I'll go ahead and make this an official part of the DynamicOrientationChanges project in a future release. Please don't be shy - give it a try and let me know how it goes!

You've got questions; I've got dumb looks [PDC10's Channel 9 Live Windows Phone 7 Q&A session available online and offline]

A few weeks ago, Microsoft held its annual Professional Developer's Conference (PDC10) and I had the privilege of being a (small!) part of it. This year's content spanned a variety of topics, including Windows Azure, HTML 5, Windows Phone 7, and more! The Channel 9 folks were there in force with two full days of live interviews - including a session on Windows Phone 7 Questions & Answers. Under the expert direction of Dan Fernandez, team members Jeff Wilcox, Peter Torr, and myself spent about 30 minutes talking about building Windows Phone 7 applications and answering questions from the (virtual) audience. It was a lot of fun, and I'd like to think it might even be educational! :)

 

Channel 9 Windows Phone 7 Question and Answer session

 

Here are the viewing options:

 

While you're at it, please check out some of the other PDC10 content online - there's a ton of good stuff and it's all free to enjoy!

The taming of the phone [New SetterValueBindingHelper sample demonstrates its usefulness on Windows Phone 7 (and Silverlight 4)]

If you've done much work with Bindings in Silverlight, you're probably aware that Silverlight doesn't support applying Bindings using a Style's Setter the same way its big brother WPF does. This limitation isn't a big deal at first because people don't tend to need that until they're more familiar with the platform and have started using MVVM and taking advantage of the ItemContainerStyle property. But once you're working with scenarios where it's relevant, being able to specify Bindings in a Setter can be extremely useful because it replaces a bunch of code/subclassing with a single line of XAML!

SetterValueBindingHelperDemo sample on Silverlight

 

Fortunately, it's possible to implement this feature outside the Silverlight framework! (Or at least to implement enough of it to cover nearly all the relevant scenarios.) I originally wrote SetterValueBindingHelper for Silverlight 3 as part of an application building exercise. Later on, I updated SetterValueBindingHelper to accommodate implementation changes in the Silverlight 4 platform - and was able to do so in a way that continued to work on Silverlight 3. So because Windows Phone 7 is based on Silverlight 3, I had a strong suspicion SetterValueBindingHelper would work there, too. But it wasn't until a couple of days ago that I had a chance to validate my theory - and now that I have, here's an updated version of the Silverlight sample for Windows Phone:

SetterValueBindingHelperDemo sample on Windows Phone 7

 

Other than converting the Silverlight sample's TreeView to a ListBox (because the former doesn't exist for Windows Phone), the sample works just the same on Windows Phone as on Silverlight. The code for SetterValueBindingHelper is nearly identical as well - the only difference being that the code to walk an application's assemblies for resolving attached property types can't be used because Windows Phone doesn't support the AssemblyPart.Load method. (But because this particular feature isn't used very often, its absence probably won't even be noticed.)

As a quick reminder, here's what a typical use looks like:

<ListBox.ItemContainerStyle>
    <Style TargetType="ListBoxItem">
        <!-- WPF syntax:
            <Setter Property="Foreground" Value="{Binding Color}"/> -->
        <Setter Property="delay:SetterValueBindingHelper.PropertyBinding">
            <Setter.Value>
                <delay:SetterValueBindingHelper
                    Property="Foreground"
                    Binding="{Binding Color}"/>
            </Setter.Value>
        </Setter>
    </Style>
</ListBox.ItemContainerStyle>
Aside: SetterValueBindingHelper supports more advanced scenarios, too - please refer to the previous post (or the original post) for information and examples.

 

[Click here to download the code for SetterValueBindingHelper along with sample applications for Silverlight 4 and Windows Phone 7.]

 

I've gotten a lot of great feedback from developers who have made use of SetterValueBindingHelper in their applications. I've found it quite helpful in my own projects, and I'm glad many of you have, too! With today's announcement, I hope another "generation" is able to use SetterValueBindingHelper to benefit from the many advantages of the Silverlight platform's rich data-binding support. :)

ListPicker? I hardly even know 'er! [A detailed overview of the Windows Phone Toolkit's ListPicker control]

In yesterday's post, I announced the second release of the Silverlight for Windows Phone Toolkit and gave an overview of the four new controls it includes. (For a discussion of the controls in the original Windows Phone Toolkit, please see my announcement for that release.) In today's post, I want to focus on one of the new controls, ListPicker, and discuss it in detail.

 

The sample application associated with the official Windows Phone Toolkit download offers a great overview of the Windows Phone Toolkit controls, but (deliberately) doesn't get into specific detail on any of them. This post is all about details, so I've written a dedicated sample application which is the source of all the XAML snippets and screenshots below:

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

 

Background

From my previous post:

ListPicker is the Windows Phone 7 equivalent of the ComboBox control: give it a list of items and it will show the selected one and also allowing the user to pick from a list if they want to change it. The core applications on Windows Phone 7 implement two kinds of list selection: an in-place expander for picking among five or fewer items, and a full-screen popup for picking among more. The Toolkit's ListPicker control combines both experiences into one handy package by automatically selecting the right UX based on the number of items in its list! It is a standard ItemsControl subclass with all the common elements of a Selector, so the API will be familiar to just about everyone. In fact, you can take most existing ListBoxes and convert them to ListPickers just by changing the control name in XAML!

That's the gist: ListPicker is the control of choice for selecting values in Windows Phone 7 applications. To be more explicit, it is most appropriate in "Settings"-like scenarios where the user is offered a variety of different options and it makes sense to display only the current value (with an option to show everything once the user decides to make a change). Conversely, ListPicker is not appropriate for displaying long lists of data that the user is going to scan and scroll; scenarios like the "People" or "Marketplace" applications are better served by a ListBox or the Windows Phone Toolkit's new LongListSelector.

 

Typical Use

The most common scenario for ListPicker looks something like this:

<StackPanel>
    <toolkit:ListPicker
        Header="Rating"
        ItemsSource="{Binding Ratings}"
        SelectedIndex="1"
        SelectionChanged="RatingSelectionChanged"/>
    <TextBlock
        x:Name="RatingSelection"
        CacheMode="BitmapCache"/>
    ...
</StackPanel>

Which gets displayed like this (in normal and expanded forms):

Typical example (normal) Typical example (expanded)

As you'd expect for an ItemsControl subclass, the ItemsSource property is used to provide the list of items (see also: the Items property). And as you'd expect for a Selector-like control, the SelectionChanged event is used to signal changes and the SelectedIndex property is used to get or set the selection (see also: SelectedItem). Everything so far looks just like ListBox - the only difference is the Header property which can optionally be used to provide a simple, platform-consistent label for the ListPicker that offers additional context about the control's purpose (see also: HeaderTemplate).

Aside: The built-in ListBox control will throw an exception if you set SelectedIndex as in the example above because it tries to apply the selection before the Binding has provided the list of items. ListPicker specifically handles this common scenario so you don't have to jump through hoops to make it work. :)

 

Custom Templates

Displaying strings is all well and good, but sometimes it's nice to display richer content:

Custom template (normal) Custom template (expanded)

The first thing to do is set the ItemTemplate property as you would for ItemsControl or ListBox - that applies the specified DataTemplate to each item and formats it attractively in the usual manner. That works great, but what about ListPicker's Full mode that's used when the list has too many items? By default, the same ItemTemplate automatically applies there, too, so you may not need to do anything more! However, the Full mode UI uses the entire screen, so it's pretty common to want to specifically customize the appearance of the items for that mode. Therefore, the FullModeItemTemplate property lets you provide a different DataTemplate to be used in the Full mode scenario. Another relevant property for such cases is FullModeHeader which sets the content that's shown at the top of the full-screen "popup".

<toolkit:ListPicker
    Header="Spectrum"
    FullModeHeader="CHOOSE COLOR"
    ItemsSource="{Binding Rainbow}"
    ItemTemplate="{StaticResource RainbowTemplate}"
    FullModeItemTemplate="{StaticResource LargeRainbowTemplate}"/>

 

Threshold Overrides

By default, lists with five or fewer items expand in-place while lists with more items switch to a full-screen selection interface. This behavior matches the platform guidelines, but sometimes it might make sense to nudge the threshold one way or another (for very large or very small items, perhaps). You might even want to force a ListPicker to always use Expanded or Full mode...

Threshold (full) Threshold (expanded)

For these scenarios, there's the ItemCountThreshold property: it specifies the maximum number of items that will be displayed in Expanded mode. In addition to nudging it up or down a bit for custom scenarios, it can also be set to 0 to "always use Full mode" or a very large number to "always use Expanded mode". Granted, an application that forces Expanded mode for a list of 1000 items probably won't be easy to use - but the freedom is there to allow developers and designers to dial-in exactly the kind of experience they want.

<toolkit:ListPicker
    Header="Rating"
    FullModeHeader="CHOOSE RATING"
    ItemsSource="{Binding Ratings}"
    ItemCountThreshold="0"/>
<toolkit:ListPicker
    Header="Spectrum"
    ItemsSource="{Binding Rainbow}"
    ItemTemplate="{StaticResource RainbowTemplate}"
    ItemCountThreshold="100"/>

 

Two-Way Binding

Two-way binding

As you'd expect, ListPicker can be used with TwoWay Bindings as well. This is particularly convenient for the SelectedIndex/SelectedItem properties where it's common to want to set the initial value based on a data model (see also: MVVM) and/or when you want the model to update directly when selection changes. The corresponding XAML looks just how you'd expect:

<toolkit:ListPicker
    Header="Network"
    ItemsSource="{Binding Networks}"
    SelectedItem="{Binding CurrentNetwork, Mode=TwoWay}"/>
<StackPanel
    Orientation="Horizontal"
    Margin="{StaticResource PhoneMargin}"
    CacheMode="BitmapCache">
    <TextBlock Text="Current Network: "/>
    <TextBlock Text="{Binding CurrentNetwork}"/>
</StackPanel>

 

Tips and Tricks

At this point, I hope everyone knows how ListPicker works and has a good feel for when/where/why/how to use it. That being the case, there are a few additional things I'd like to draw attention to:

  1. The ListPicker philosophy is that "there is always an active selection", so it makes sure to select an item when it initializes or when the list changes. This automatic selection (of the first item in most cases) causes the SelectionChanged event to fire - and that causes the application's associated event handler to run (assuming one has been registered). In practice, this "initialization-time" event catches some people by surprise - but it's the intended behavior (and folks tend to agree it's correct once they understand why it happens). Now that you know about it, maybe your development experience will be a bit easier. :)

    Aside: If you want to ignore this event in code, it should be easy to detect because its SelectionChangedEventArgs.RemovedItems collection will be empty (have 0 items). And the only time that happens is when ListPicker is transitioning from an empty list to a non-empty one (e.g., on startup).
  2. ListPicker's transitions between Normal and Expanded mode are effectively animations of the control's Height. Because Height changes cause a layout pass, they don't take place on the composition thread and therefore are more susceptible to performance issues. An easy way to mitigate this in the typical "list of items in a StackPanel" scenario is to add CacheMode=BitmapCache to the elements that appear below the ListPicker (i.e., those that are pushed down by the animation). Please refer back to the first XAML snippet for an example - this tweak allows the Silverlight layout system to animate such controls as bitmaps and that helps the animation run a bit more smoothly.

    Aside: If you don't want to apply BitmapCache to every control individually, an alternate approach is to wrap the affected controls in another StackPanel and set the CacheMode property on the StackPanel instead. Please see the last XAML snippet above for an example of this.
  3. If you have a long list of controls in a StackPanel inside a ScrollViewer and there's a ListPicker near the bottom using Expanded mode, that expansion does not automatically scroll the screen to keep the ListPicker completely in view. On WPF, the fix would be a simple matter of calling FrameworkElement.BringIntoView. However, Silverlight doesn't have that API and there doesn't seem to be a good general purpose way for ListPicker to find the right parent to scroll. (Although walking up the visual tree to find the first ScrollViewer is probably right in most cases, it's not a sure thing; ListPicker errs on the side of caution and doesn't try to make guesses.) In practice, the underlying issue doesn't come up very often - when it has, my suggestion has been to use the ItemCountThreshold property to force the relevant ListPicker to use Full mode (which doesn't expand, so it doesn't alter the parent's layout, so it doesn't have this problem).

 

Summary

ListPicker is a relatively straightforward control that should be familiar to anyone who's used the standard ListBox. But while its API may be unremarkable, its user experience is all Windows Phone 7 goodness! :)

I hope you enjoy it!

Mo controls, mo controls, mo controls... [Announcing the second release of the Silverlight for Windows Phone Toolkit!]

I'm happy to report that we've just published the Silverlight for Windows Phone Toolkit November 2010 release! This is the second iteration of the Windows Phone Toolkit and effectively doubles the number of controls we've created to help developers and designers build more compelling, more platform-consistent user experiences with ease. The first Windows Phone Toolkit release has been a big hit and we've seen a lot of developers using it (in both binary and source forms) to build their Windows Phone 7 applications. But while we tried to address the most pressing needs with that release, there were still a couple of prominent controls missing...

With today's update, we've tried to provide more of the fundamental controls customers have been asking for - as well as API documentation and fixes for some of the bugs people reported with the first release. Recall that the Windows Phone Toolkit is published on CodePlex under the Ms-PL open-source license so anyone who wants can look at the source code to learn how we've done things - or customize any control to suit their specific scenario. As always, if you have suggestions for things we should add or change, please search the CodePlex issue tracker and vote for the issue (or create a new one if the idea is unique). We use your input to help prioritize our efforts and ensure we're delivering the right things for the community!

 

What's New?

 

ListPicker

ListPicker sample ListPicker popup sample
<toolkit:ListPicker Header="background">
    <sys:String>dark</sys:String>
    <sys:String>light</sys:String>
    <sys:String>dazzle</sys:String>
</toolkit:ListPicker>

ListPicker is the Windows Phone 7 equivalent of the ComboBox control: give it a list of items and it will show the selected one and also allow the user to pick from a list if they want to change it. The core applications on Windows Phone 7 implement two kinds of list selection: an in-place expander for picking among five or fewer items, and a full-screen popup for picking among more. The Toolkit's ListPicker control combines both experiences into one handy package by automatically selecting the right UX based on the number of items in its list! It is a standard ItemsControl subclass with all the common elements of a Selector, so the API will be familiar to just about everyone. In fact, you can take most existing ListBoxes and convert them to ListPickers just by changing the control name in XAML!

 

LongListSelector

LongListSelector movies sample LongListSelector people sample LongListSelector jump-list sample
<toolkit:LongListSelector
    ItemsSource="{StaticResource movies}"
    ListHeaderTemplate="{StaticResource movieListHeader}"
    GroupHeaderTemplate="{StaticResource movieGroupHeader}"
    GroupFooterTemplate="{StaticResource movieGroupFooter}"
    GroupItemTemplate="{StaticResource groupItemHeader}"
    ItemTemplate="{StaticResource movieItemTemplate}">
</toolkit:LongListSelector>

While ListPicker is about simple selection scenarios, LongListSelector is about advanced ones! Think of it as ListBox++--, it has everything you expect from ListBox plus a bunch of advanced capabilities and great on-device performance minus the levels of abstraction and generality that tend to slow ListBox down. LongListSelector supports full data and UI virtualization, flat lists, grouped lists (with headers!), and also implements the "jump list" header navigation UI that makes the "People" app so efficient! The theory behind LongListSelector is that it should be easy to fix a poorly-performing ListBox scenario by swapping in a LongListSelector instead: it handles all the tricky parts for you, so there's less to worry about and it "just works". Unless you've spent a lot of time fine-tuning your application's list behavior, you should see improved performance by switching to LongListSelector!

 

TransitionFrame (and Transitions)

TransitionFrame sample
RootFrame = new TransitionFrame();
<toolkit:TransitionService.NavigationInTransition>
    <toolkit:NavigationInTransition>
        <toolkit:NavigationInTransition.Backward>
            <toolkit:TurnstileTransition Mode="BackwardIn"/>
        </toolkit:NavigationInTransition.Backward>
        <toolkit:NavigationInTransition.Forward>
            <toolkit:TurnstileTransition Mode="ForwardIn"/>
        </toolkit:NavigationInTransition.Forward>
    </toolkit:NavigationInTransition>
</toolkit:TransitionService.NavigationInTransition>
<toolkit:TransitionService.NavigationOutTransition>
    <toolkit:NavigationOutTransition>
        <toolkit:NavigationOutTransition.Backward>
            <toolkit:TurnstileTransition Mode="BackwardOut"/>
        </toolkit:NavigationOutTransition.Backward>
        <toolkit:NavigationOutTransition.Forward>
            <toolkit:TurnstileTransition Mode="ForwardOut"/>
        </toolkit:NavigationOutTransition.Forward>
    </toolkit:NavigationOutTransition>
</toolkit:TransitionService.NavigationOutTransition>

The Windows Phone UI Guidelines encourage smooth, attractive page-to-page animations like the core applications show, but there has been little platform support for creating similar experiences in your own applications - until now! :) The new transition classes in the Windows Phone Toolkit aims to make it easy for application developers to add attractive, platform-consistent transitions to their applications. All that's necessary to enable transitions for an application's pages is tweak App.xaml.cs (shown above) and add a bit of XAML to each page to specify its transitions (also shown above). Everything else is done for you!

Aside: This release includes support for multiple flavors of the following transitions: turnstile, slide, rotate, swivel, and roll. It's also possible to implement custom transitions using the same framework!

 

AutoCompleteBox

AutoCompleteBox sample
<toolkit:AutoCompleteBox
    ItemsSource="{StaticResource words}"/>

AutoCompleteBox first appeared in the Silverlight 2 Toolkit, then later graduated to the Silverlight 3 SDK. Now it's back in the Toolkit - this time for Windows Phone 7! Because phones are about being small and quick to use, simplifying tedious tasks like text input is an important goal. Toward that end, a number of the core applications (like Bing search) make use of auto-completion to predict what the user is typing and save time by allowing them to click on the completed word instead. AutoCompleteBox makes it easy to bring the same convenience to your own applications by taking advantage of a phone-friendly implementation of this popular Silverlight control. By providing a suitable completion list (in any of a variety of ways), users are automatically prompted with the relevant matches as they start typing!

 

API Documentation

CHM file example

The source code for the Windows Phone Toolkit has included full XML Documentation Comments from the beginning, but now we've begun generating a separate CHM file with all the property/method/event comments in a single, easy-to-browse location. The documentation file is automatically installed by the Windows Phone Toolkit installer and a handy link is added to the "Silverlight for Windows Phone Toolkit" folder in the Start Menu. Because we don't have dedicated documentation writers on the Toolkit team, our documentation is a bit on the terse side - but the CHM file is still a great way to survey the Toolkit classes and get a feel for what's available. And because the sample syntax is available in both C# and VB, everyone should be comfortable with the examples!

 

Bug fixes for existing controls

The previous Toolkit release wasn't all that long ago and we've been quite busy since then, but we've still managed to squeeze in fixes for some of the more annoying bugs customers reported. That's not to say that we fixed them all or that we had a chance to squash your favorite bug, but we were fortunate to be able to fix a good number of customer-impacting issues and I hope everyone finds the new controls even more pleasant to use! :)

 

[Click here to download the Silverlight for Windows Phone Toolkit November 2010 release.]

 

The screen shots and XAML shown above are all from the sample application you can download along with the Toolkit. I encourage people to play around with the sample if they want to experiment with any of these controls (in the emulator or on the device) or if they want to learn more about how these controls work. I anticipate more in-depth coverage will show up in the coming weeks (I will be posting a detailed ListPicker overview tomorrow!), but for now the sample application is a great springboard to get folks started!

 

In closing, I'm really glad we've been able to get this second round of controls out to the community in such a short time! While there are probably still some "nice to have" controls that could be added to further round-out the Windows Phone 7 control offering, I think that what we've included in the Windows Phone Toolkit represents nearly all the critical ones needed to unblock important scenarios. I hope people continue to enjoy their Windows Phone development experience and that the new Windows Phone Toolkit makes application development even easier! :)