I really like the pull-down-and-release-to-refresh gesture seen in various smartphone apps. In my opinion it doesn't conflict with the Metro UI guidelines, so I don't see any reason why it shouldn't be used in a WP7 app. Here is an explanation of how it can be done in WP7 without much difficulty. If you just want the complete source code, jump to the end to download the source along with a demo project.

The WP7 ScrollViewer control has a built-in stretchy feel to it if you try to pull it down from the top or up from the bottom, so it is already well-suited to this kind of interaction. What we need to do is detect when and how far the ScrollViewer is pulled down from the top, when it is released from that point, and also reveal an indicator control "behind" the ScrollViewer to provide visual feedback as it is pulled down. And since a ListBox uses a ScrollViewer internally to scroll its items, the same solution will work just as well with a ListBox.

Detecting a pull-down motion

The ScrollViewer class does not directly publish any events about its scrolling motion. So, how can we know when the ScrollViewer is being "pulled down"? With a little experimentation, I found that the ScrollViewer applies a CompositeTransform to its Content for vertical translation (and subtle compression) when the contents are dragged down from the top or up from the bottom. But for normal scrolling through the length of the list, the CompositeTransform is just equivalent to an identity transform (0 translation, 1.0 scale). This makes it very easy to know when and how far the ScrollViewer is pulled down from the top: just look for a positive Y translation on the RenderTransform of the content.

Caution: This technique relies on undocumented internal behavior of the ScrollViewer. It's possible that a future revision of the ScrollViewer could change its internal scroll rendering in a way that breaks this kind of pull-to-refresh code. I even hesitate to blog this for that reason, however in my estimation the risk is low, and can be mitigated in a couple ways: Any code depending on the current scroll rendering behavior should degrade gracefully (don't crash when something expected is not found), and the app should provide some alternate means of refreshing the scrolled contents such as a context menu etc. I have no official knowledge on this subject, and I can't even guarantee that an app that implements this gesture will pass the marketplace review process. So let me know how it works out!

Moving beyond the disclaimer, here's a snippet of code showing how to handle a ScrollViewer's mouse-move event to detect a pull-down gesture.

void targetScrollViewer_MouseMove(object sender, MouseEventArgs e)
{
    UIElement scrollContent = (UIElement)this.targetScrollViewer.Content;
    CompositeTransform ct = scrollContent.RenderTransform as CompositeTransform;
    if (ct != null)
    {
        if (ct.TranslateY > this.PullThreshold)
        {
            // Show the ready-to-release indicator
        }
        else if (ct.TranslateY > 0)
        {
            // Show the pull-down indicator
        }
        else
        {
            // Hide the indicators
        }
    }
}

Detecting a release is very similar: handle a mouse-up event and check whether the Y translation at the time of release is greater than the minimum distance.

Revealing a pull-down indicator

There are a few ways to reveal another control as the ScrollViewer is pulled down. The easiest method is to layout the control directly behind the ScrollViewer, and make the ScrollViewer contents opaque so that the control is normally covered. But I wanted to allow for a transparent background on scrolled items, as is very typical. So, the solution I settled on has a control that is initially 0-height and has its height dynamically adjusted as the ScrollViewer is pulled down. To implement this, I created a PullDistance DependencyProperty that gets dynamically updated by the mouse-move event handler, and bound the Height property of the pulling-down indicator to that. For additional visual effect, I created a similar PullFraction property and bound it to the indicator's Opacity, so that the indicator fades in proportional to the pull-down.

The full XAML is too verbose to post inline, but here's a small snippet from the control template that shows the bindings mentioned above.

<StackPanel x:Name="PullingDownPanel"
    Height="{TemplateBinding PullDistance}" Opacity="{TemplateBinding PullFraction}"
    Margin="{Binding PullDistance, RelativeSource={RelativeSource TemplatedParent},
 Converter={StaticResource NegativeValueConverter}, ConverterParameter=Bottom}">
    <ContentPresenter ContentTemplate="{TemplateBinding PullingDownTemplate}" />
</StackPanel>

Note the Margin binding, which is a bit tricky. The purpose of that is to apply a negative bottom margin opposite to the height, in order to keep the layout height of the control at 0. The custom value-converter class converts a double value into a Thickness object with negative margin of the same magnitude. Without it, the entire ScrollViewer would get "pushed" down as the control before it was enlarged.

Putting it all together

With the two tricky parts done, the rest is pretty typical for building custom controls. I'm not going to walk though the details here, as the concepts are covered well in other places. But here's a brief list of what else went into my PullDownToRefreshPanel custom control:

• A RefreshRequested event to signal the app when the user has completed the refresh gesture
• DataTemplate properties for each of the three indicators (pulling down, ready to release, refreshing) to allow customizing those visuals without needing to re-template the whole control
• Visual-state definitions in the control template XAML to control the visibility of each of the templates according to the current visual state
• An IsRefreshing property to allow the app to easily enter and exit the refreshing visual state (which shows an indeterminate progress bar by default)
• Automatic detection of a nearby ScrollViewer or ListBox -- just put the PullDownToRefreshPanel in the same parent container and it will hook itself up

Demo

For demonstration purposes, I've added the PullDownToRefreshPanel code to my ReorderListBox demo app. It should work just as well with any other ListBox or ScrollPanel. Sorry, it won't work with a LongListSelector -- that control does custom scrolling without using a ScrollViewer. I've attached to this post a ZIP containing source code for both controls and the demo project.

ReorderListBox-WP71.zip

Update 2011-12-19: Updated the attached demo project to target the WP 7.1 (Mango) SDK. This required a small change to the auto-scroll logic.

The ReorderListBox control I shared last week was moderately popular, and I've received some great feedback. Today I'm sharing an update to that control that polishes some minor issues and adds a cool new feature I call "rearrange animations". This feature allows the application to programmatically move, insert, or delete items in the list while showing a nice visual indication of what is happening. Specifically, the animations are as follows:

• Inserted items fade in while later items slide down to make space.
• Removed items fade out while later items slide up to close the gap.
• Moved items slide from their previous location to their new location.
• Moved items which move out of or in to the visible area also fade out / fade in while sliding.

The rearrange animations are complementary to the interactive drag-and-drop reordering, and both features can be enabled at the same time. Unfortunately the rearrange animations are not customizable in XAML due to the way they must be dynamically generated. And when using them you'll have to keep performance in mind: if you make a lot of changes to a large list (such as a full shuffle or sort) then the rearrange animations may take some time to prepare, although once the animations start they should be smooth. In my tests on a Samsung Focus, such complex rearrangements took up to about a second to prepare. Simpler operations such as moving, adding, or removing an item or two are much faster.

Updated source is attached at the ReorderListBox CodePlex site. Here's a complete list of what else has changed since last week:

• When an item is dropped, it now quickly slides into its proper position rather than suddenly appearing there.
• Control templates are corrected: a few things were missing compared to the standard ListBox control template, most notably the selected-item accent color.
• The scrollbar is now made visible while drag-scrolling.
• Fixed a bug that prevented moving a taller item to the top or bottom position when a shorter item was there.
• Fixed a bug that caused the list items to jump slightly after moving an item down by more than a page then dropping it.

And now, a video preview of the improved ReorderListBox control!

Update 2011-01-03: An improved version of this control is available.

For a Windows Phone 7 application I was building, I needed a way for the user to easily drag to re-order items in a list. My searches for any existing examples turned up nothing, so I set out to build a custom control myself. It was challenging to say the least, and it forced me to learn a lot more about Silverlight including custom controls, ListBox virtualization, visual states and transitions. (I was certainly not an expert to start with.)

Overall, I'm pretty happy with how it turned out.

• It's a drop-in replacement for a standard ListBox. All properties including item templates still work.
• It's compatible with data-binding: the reordering is propogated back to the items source list.
• It works with ListBox's automatic virtualization to support large item collections efficiently.
• The list scrolls automatically while dragging up or down near the top or bottom margin.
• Visuals are fully template-driven, making use of visual states and transition animations.
• When dragging, the other items smoothly move around to make space for the dragged item.
• The reorder capability can be enabled or disabled via a dependency property.

Each list item has a "handle" shown when reordering is enabled. Dragging on the handle will drag the item up or down, with a semi-transparent highlight. Dragging anywhere else over the list area will scroll the list normally. The default appearance of the handle is shown below, but it is styleable.

Source code and a simple demo app are in the attached ZIP published in the CodePlex project. Please let me know how it works out for you!

An error occurred trying to load the page.
Value does not fall within the expected range.

Update: As another symptom of the same issue, you may also experience problems with source control check-out with any projects in the solution.

The breaking changes were introduced in WiX builds 3.0.4109 - 3.0.4220, so a .wixproj created with a build <4109 will have problems when used with a build >=4220. I'll explain the changes here and show you how to update older project files to work with newer WiX builds.

The changes are all about the default and available platform configurations of WiX projects. Previously, WiX projects always had a platform of "Any CPU", and there was no way to change it. But actually MSI packages are somewhat platform-specific: a package is marked as either 32bit or 64bit, and cannot be both. While a 32bit MSI can install on a 64bit OS, it's a bit like a 32bit EXE running on WoW in that it can't easily interact with any of the 64bit parts of the system.

The WiX command-line toolset has long enabled building both 32bit and 64bit MSIs, and more developers are starting to build 64bit packages, so we thought it made a lot of sense to expose that capability in the natural Visual Studio representation: project platforms. With the latest builds, a new WiX project has its configuration set to "x86" by default, and you can use the VS Configuration Manager to add an additional "x64" platform if you need it. (IA64 support is not yet implemented... is there any demand?) Also "Any CPU" is no longer a valid platform for WiX projects -- it was only there because Votive builds on a VS project framework was originally designed for compiling .NET languages.

If you have WiX projects that were created with an older WiX build and you want to continue to use them with a newer build without recreating the projects, use the following steps:

1. Install the new build of WiX.
2. In VS, open the solution that includes one or more WiX projects.
3. For each WiX project node in the solution explorer, right-click and Unload Project, then right-click again and Edit the .wixproj.
4. Change the conditional expression on each configuration PropertyGroup to include an "x86" platform:
   

   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">

   ...

   <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">

5. Right-click on the project node and Reload the project.
6. From the Build menu, open the Configuration Manager tool. Ensure that each WiX project is selected to build (if desired) for each solution configuration.

The C++ project sets you up with the WiX unmanaged CA utility library (wcautil), while the C# and VB projects use the DTF library for managed-code MSI custom actions. I assume you're here because you want to read more about the latter.

When DTF first released with WiX last week, it included some sparse documentation about how to create a post-build step to package up your managed CA assembly in a form callable by MSI. I apologize to anyone who jumped on it right away and had trouble hooking things up (which was only made more difficult by a missing binary that had to be built from source). I should have had these templates ready then.

When you create a C# custom action project from the new template, the project has the necessary post-build step hooked up already. For the curious, those build rules are in %ProgramFiles%\MSBuild\Microsoft\WiX\v3.0\wix.ca.targets. Building the custom action project will produce an additional DLL in the target directory with the name $(TargetName).CA.dll. That is the DLL to be streamed into your MSI Binary table. Since that DLL exports ordinary entrypoints callable directly by the MSI engine, you can use it with any MSI authoring tool as if it was an unmanaged CA DLL.

The custom action build process will automatically package up any non-GAC'd assemblies that your CA depends on. (Make sure the Copy Local property is set to 'true' on the reference node if you want it included.) Those dependencies will include at a minimum the Microsoft.Deployment.WindowsInstaller.dll assembly from DTF. Additionally, any items in the project with a Build Action of 'Content' will be included in the CA package. CustomAction.config is the sole Content file in the template; your CA may require additional resources or data files at runtime.

In Votive, a convenient way to consume the custom action DLL in your setup is via a project reference:

1. Create a solution with a WiX MSI or WiX Library project and a C# or VB custom action project.
2. Add a reference from the WiX project to the custom action project.
3. Author the custom action in your setup with WiX code similar to the fragment below. Note you may need to change some attributes in the XML, depending on your CA and how it executes.

As I said in my introduction, in previous years I spent a lot of time working on internal deployment-related tools. Specifically these were tools for authoring, building, installing, testing and debugging MSIs and MSPs for DevDiv products, mostly Visual Studio and .NET Framework. I found very early that programming against the Windows Installer APIs in C++ is a slow and sometimes arduous task, and while script is easier to write it's not a robust scalable solution. I wanted to take advantage of the great productivity gains of the then-new .NET platform, so I started by creating a limited interop library for accessing the MSI APIs from a .NET language. As I worked on more tools, I gradually filled out and improved that interop library. I also added a cabinet library since working with MSI setups often involves dealing with cabinets.

After sharing it with a few other teams in the company who were also working on deployment related tools, I got great feedback on the value of the project, which motivated me to cover the remaining MSI APIs and add more documentation to make it a more complete framework. Most of this work was actually done outside of my day job -- I would work a few evenings and weekends on the project now and then, just motivated by the positive feedback and knowing that I was making other developers' jobs easier.

The debate about managed custom actions is nearly as old as managed code. While the .NET Framework has always provided an InstallUtil tool that lets you invoke managed assembly Installer classes during the setup, it is, to be blunt, a managed version of self-reg suffering from nearly all the problems that plague classic DLL self-registration. That means InstallUtil custom actions usually are not a good idea if you're interested in creating a really clean and robust setup. Still, if you're working with a product or platform that's all based on managed code, it's likely your setup will need to run managed code to intract with it.

So with the DTF project I took on the challenge of enabling real managed custom actions that have all the capabilities of unmanaged custom actions in terms of access to the installer session, allowing them to follow the best practices for data-driven custom actions. Given that I already had a library that exposed all the MSI APIs in managed code, I was halfway there, or so I thought. Over the years I went through three major design iterations for how the managed-code CA got launched. While the earlier designs seemed to work well, they suffered from some subtle robustness issues related to interactions between the CLR and the MSI engine. It wasn't until last summer that I finally overcame the last technical hurdle (described in Rob's blog post) to achieve what I believe now is a robust framework for managed custom actions.

For several years I've been looking for a way to release the DTF project externally, since I think there are lots of developers who would find it useful. There have been a number of reasons why it didn't happen until now. For a while the MSI team was hinting that they might implement their own set of official managed APIs for the Windows Installer platform (and I didn't want to cause confusion with an alternative), but now it doesn't look like that will happen anytime soon if ever. Also I didn't want to release a framework for managed custom actions until I had something that addressed robustness issues with CLR and MSI interactions.

The final barrier to releasing DTF was the strategic concern, also described by Rob, about wanting to reduce people's reliance on custom actions in their setups. Personally on this issue I've always been somewhat of a pragmatist: the MSI platform can never support everything that people might possibly need to do in their setups, so there will always be a need for some custom actions. And if my framework can make it easier for those people to write quality custom actions, I think that's a good thing. Now that a few other key people here have more or less come around to that point of view, DTF could finally be released. I hope all the developers out there will prove us right by not writing too many crazy ill-conceived managed custom actions.

I've been a developer at Microsoft for about 8 years now, and have spent most of that time working on various areas of software deployment. For a long time it was primarily internal tools, which is why you haven't seen much of me out here. More recently I've become the lead for a team in the Deployment Technology Group in DevDiv responsible for integrating WiX and Votive into the next release of Visual Studio. This means I've been working closely with others you may know in the WiX community including Rob, Justin, Bob, Peter, and Heath.

In addition to software deployment, I'm passionate about managed code and developer tools, so I spend a lot of time working on the intersection of those thre areas. This passion has led directly to my work on the DTF project, which I am excited to talk about in upcoming blog posts.