Updated for the RTM tools, included sample application to show how it’s used.
For my ongoing ‘research project’ on making the user experience for my MVVM-driven map viewer for Windows Phone 7 a bit better I wanted to make some changes to the header. Initially you could swipe the header which showed which map you show, but it gave no indication that you actually could make the swipe, or that other maps were available. I set out to create a behaviour, and ended up building a control. In my map viewer, it currently looks and works like this:
And, of course, it needed to play along nicely with MVVM. And therefore it has three bindable properties:
- Items: an IList of basically anything
- SelectedItem: the currently selected item in Items
- DisplayText: (optional): the name property of the objects in Items which value should be used in de SwipeTitle. If skipped, the ToString() value of the objects is used as a display value.
It does not sport item or data templates (yet) – it’s just meant to be plug and play. For now.
Usage
You only have to do six things to use this thing:
- Create an empty Windows Phone 7 application
- Add the LocalJoost.Controls project included in the demo solution to your project.
- Create some kind of model with a property containing a list of objects and a property containing a selected object and bind it to the layout root
- Drag the SwipeTitle control on the design surface at the place of the TextBox called “PageTitle” (and remove PageTitle)
- Bind property Items, SelectedItem and DisplayText as needed
- Make sure the Width property of the StackPanel “TitlePanel” is some large width, e.g. 2000.
Below is a short walkthrough of the source. Those who just want to use it, can just grab the source. If you want a simple sample application showing the usage of the control, just grab this solution and see how it works. I sincerely apologize for the sheer silliness of the demo solution, it was all I could think of on short notice.
Walkthrough
The XAML is pretty simple: three TextBlocks in a horizontal StackPanel:
<UserControl x:Class="WP7Viewer.SwipeTitle"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d"
FontFamily="{StaticResource PhoneFontFamilyNormal}"
FontSize="{StaticResource PhoneFontSizeNormal}"
Foreground="{StaticResource PhoneForegroundBrush}"
d:DesignHeight="480" d:DesignWidth="480">
<StackPanel Grid.Row="1" Orientation="Horizontal" x:Name="pnlSwipe">
<TextBlock x:Name="tbPrevious"
Foreground="Gray"
Text="Previous"
Margin="0,0,0,0"
Style="{StaticResource PhoneTextTitle1Style}">
</TextBlock>
<TextBlock x:Name="tbCurrent"
Text="Current"
Margin="20,0,0,0"
Style="{StaticResource PhoneTextTitle1Style}">
</TextBlock>
<TextBlock x:Name="tbNext"
Foreground="Gray"
Text="Next"
Margin="20,0,0,0"
Style="{StaticResource PhoneTextTitle1Style}">
</TextBlock>
</StackPanel>
</UserControl>
You can swipe endlessly left or right, when it comes to the end or the start of the list it just adds the items from the start or the end again. The middle text is the selected object, and is always shown (in white). When you swipe the text to the left, it animates the swipe to completion: the text previously on the right, which you swiped into view, is now displayed in the middle TextBlock. The text that used to be in the middle block, is now in the left, and in the right TextBlock a new text from Items is displayed, as shown in the video.
Now how does this work? If you know how to do it, it is – as everything – pretty simple. First, some boring stuff, the class definition with some members and dependency properties:
using System;
using System.Collections;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
namespace WP7Viewer
{
public partial class SwipeTitle
{
/// <summary>
/// An internal linked list to make searching easier
/// </summary>
private LinkedList<object> _displayItems;
private TranslateTransform _transform;
private int _currentDisplayItem = 1;
#region Items
/// <summary>
/// Dependency property holding the items selectable in this control
/// </summary>
public static readonly DependencyProperty ItemsProperty =
DependencyProperty.Register("Items", typeof(IList),
typeof(SwipeTitle), new PropertyMetadata(ItemsChanged));
private static void ItemsChanged(object sender,
DependencyPropertyChangedEventArgs args)
{
var c = sender as SwipeTitle;
if (c != null) { c.ProcessItemsChanged(); }
}
public IList Items
{
get { return (IList)GetValue(ItemsProperty); }
set { SetValue(ItemsProperty, value); }
}
public void ProcessItemsChanged()
{
_displayItems = new LinkedList<object>();
foreach (var obj in Items) _displayItems.AddLast(obj);
SelectedItem = Items[0];
}
#endregion
#region SelectedItem
/// <summary>
/// Dependency property holding the currently selected object
/// </summary>
public static readonly DependencyProperty SelectedItemProperty =
DependencyProperty.Register("SelectedItem", typeof(object),
typeof(SwipeTitle), new PropertyMetadata(SelectedItemChanged));
private static void SelectedItemChanged(object sender,
DependencyPropertyChangedEventArgs args)
{
var c = sender as SwipeTitle;
if (c != null) { c.ProcessSelectedItemChanged(); }
}
// .NET Property wrapper
public object SelectedItem
{
get { return (object)GetValue(SelectedItemProperty); }
set { SetValue(SelectedItemProperty, value); }
}
public void ProcessSelectedItemChanged()
{
UpdateDisplayTexts();
ScrollToDisplayItem(1, false);
}
#endregion
#region DisplayField
public string DisplayField
{
get { return (string)GetValue(DisplayFieldProperty); }
set { SetValue(DisplayFieldProperty, value); }
}
public static readonly DependencyProperty DisplayFieldProperty =
DependencyProperty.Register("DisplayField", typeof(string),
typeof(SwipeTitle), null);
#endregion
}
}
}
The transformation is used in the animation and to make sure the middle TextBlock is displayed when idle. I tend to tuck dependency properties in regions to keep stuff a bit organized, but feel free to do otherwise. Note, however, that the objects in Items are immediately copied in a LinkedList _displayItems – I use this list to make it easier to find previous and next objects.
Then we need a little method to get the display text from the objects according to the value of “DisplayField”:
/// <summary>
/// Retrieve the display value of an object
/// </summary>
/// <param name="displayObject"></param>
/// <returns></returns>
private string GetDisplayValue( object displayObject)
{
if (DisplayField != null)
{
var pinfo = displayObject.GetType().GetProperty(DisplayField);
if (pinfo != null)
{
return pinfo.GetValue(displayObject, null).ToString();
}
}
return displayObject.ToString();
}
To show or update the displayed texts, according the object that is selected (in SelectedItem), the UpdateDisplayTexts method is needed. This is fired when Items or SelectedItem is changed. It finds SelectedItem and puts it in the middle TextBlock, and finds the texts that need to be before and after it, using the LinkedList _displayItems.
/// <summary>
/// Shows (possible) new texts in the three text boxes
/// </summary>
private void UpdateDisplayTexts()
{
if (_displayItems == null) return;
if (SelectedItem == null)
{
SelectedItem = _displayItems.First.Value;
}
tbCurrent.Text = GetDisplayValue(SelectedItem);
var currentNode = _displayItems.Find(SelectedItem);
if (currentNode == null) return;
tbNext.Text =
GetDisplayValue(currentNode.Next != null ?
currentNode.Next.Value : _displayItems.First.Value);
tbPrevious.Text =
GetDisplayValue(currentNode.Previous != null ?
currentNode.Previous.Value : _displayItems.Last.Value);
}
Now I need to set up and implement some events in the control:
- The items must be initially displayed, after the control is loaded
- When the user swipes the title, it must follow his finger
- When the user stops swiping, it must decide whether the user has swiped far enough to select the next item (and if not, revert the swipe), and if the swipe was far enough, select the next item
- When the next item is selected, show the new selected text in the middle again.
public SwipeTitle()
{
InitializeComponent();
_transform = new TranslateTransform();
pnlSwipe.Loaded += (sender, args) => ProcessSelectedItemChanged();
pnlSwipe.ManipulationDelta += pnlSwipe_ManipulationDelta;
pnlSwipe.ManipulationCompleted += pnlSwipe_ManipulationCompleted;
pnlSwipe.RenderTransform = _transform;
tbPrevious.SizeChanged += tbPrevious_SizeChanged;
}
void pnlSwipe_ManipulationDelta(object sender, ManipulationDeltaEventArgs e)
{
_transform.X += e.DeltaManipulation.Translation.X;
}
/// <summary>
/// Caculates the screen width
/// </summary>
private static double ScreenWidth
{
get
{
var appFrame = Application.Current.RootVisual as Frame;
return null == appFrame ? 0.0 : appFrame.RenderSize.Width;
}
}
/// <summary>
/// Fired after manipulation is completed. When the title has been moved over 25% of the
/// screen, the next or previous item is selected
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void pnlSwipe_ManipulationCompleted(object sender, ManipulationCompletedEventArgs e)
{
if (e.TotalManipulation.Translation.X > .25 * ScreenWidth)
{
ScrollToDisplayItem(_currentDisplayItem - 1, true);
}
else if (e.TotalManipulation.Translation.X < -.25 * ScreenWidth)
{
ScrollToDisplayItem(_currentDisplayItem + 1, true);
}
ScrollToDisplayItem(_currentDisplayItem, true);
}
/// <summary>
/// Fired when new data is put into the last object.
/// Rendering is then finished - the middle text is showed in the middle again
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void tbPrevious_SizeChanged(object sender, SizeChangedEventArgs e)
{
ScrollToDisplayItem(1, false);
}
In the constructor the members are initialized – particularly the transform – which is set to the StackPanel surrounding the three TextBlocks. When the user now swipes, the texts appear to follow him. When, in pnlSwipe_ManipulationCompleted, the user has dragged the text over more than 25% of the screen, it scrolls the text further until the newly selected items is fully into view. If the text value of the last box is changed, we need to reset the middle TextBlock in the center again – but now without animation, and so it will seem if the scrolling text suddenly changes in color and appears to be selected.
Notice a little gem in here – the ScreenWidth property. It turns out you can determine the actual screensize by trying to cast the RootVisual to a Frame, and then check it’s RenderSize.
All that is left now, basically, is the implementation of ScrollToDisplayItem – and a companion method, as shown below:
/// <summary>
/// Scrolls to one of the 3 display items
/// </summary>
/// <param name="item">0,1 or 2</param>
/// <param name="animate">Animate the transition</param>
void ScrollToDisplayItem(int item, bool animate)
{
_currentDisplayItem = item;
if (_currentDisplayItem < 0) _currentDisplayItem = 0;
if (_currentDisplayItem >= pnlSwipe.Children.Count)
{
_currentDisplayItem = pnlSwipe.Children.Count - 1;
}
var totalTransform = 0.0;
for (var counter = 0; counter < _currentDisplayItem; counter++)
{
double leftMargin = 0;
if (counter + 1 < pnlSwipe.Children.Count)
{
leftMargin =
((Thickness)(pnlSwipe.Children[counter + 1].GetValue(MarginProperty))).Left;
}
totalTransform +=
pnlSwipe.Children[counter].RenderSize.Width + leftMargin;
}
var whereDoWeGo = -1 * totalTransform;
if (animate)
{
//Set up the storyboard and animate the transition
var sb = new Storyboard();
var anim =
new DoubleAnimation
{
From = _transform.X,
To = whereDoWeGo,
Duration = new Duration(
TimeSpan.FromMilliseconds(Math.Abs(_transform.X - whereDoWeGo)))
};
Storyboard.SetTarget(anim, _transform);
Storyboard.SetTargetProperty(anim, new PropertyPath(TranslateTransform.XProperty));
sb.Children.Add(anim);
sb.Completed += sb_Completed;
sb.Begin();
}
else
{
_transform.X = whereDoWeGo;
}
}
/// <summary>
/// Fired when an animation is completed. Then a new items must be selected
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void sb_Completed(object sender, EventArgs e)
{
if (SelectedItem != null)
{
var currentNode = _displayItems.Find(SelectedItem);
if (_currentDisplayItem == 0)
{
SelectedItem = (currentNode.Previous != null ?
currentNode.Previous.Value : _displayItems.Last.Value);
}
if (_currentDisplayItem == 2)
{
SelectedItem = (currentNode.Next != null ?
currentNode.Next.Value : _displayItems.First.Value);
}
UpdateDisplayTexts();
}
}
In ScrollToDisplayItem the text is either moved or animated in the right direction, and when the animation is finished, the TextBlocks are updated with values according to the swipe direction. If no animation is needed – which occurs initially, or after the texts are updated – the transform is simply applied in stead of animated.
Credits
Important parts of the code came into being during a joint hacking evening at
Sevensteps in Amersfoort, Netherlands, at August 31 2010. My sincere thanks to
Bart Rozendaal,
Kees Kleimeer and
Pieter-Bas IJdens, all of Sevensteps, who basically coded the method pnlSwipe_ManipulationCompleted and the property ScreenWidth, almost all of the ScrollToDisplayItem method, and in addition supported me with wine, snacks and enjoyable company during that memorable evening.
