Transition Guide to the official Panorama and Pivot controls

Do you know additional migration tips & tricks ?
Feel free to drop me an email or leave a comment below.

Why use the official controls

This project was built as a temporary solution. While it allowed you to start developing Panoramic or Pivot experiences for Windows Phone 7, it lacks some attributes of quality controls such as :

• Fully tested
• Optimized for memory footprint and performance
• VSM & Templating support
• Design-time support
• UX approved by WP7 design team
• Officially supported by a team of professionals, with long term commitment to the quality of the controls

The final release of the Windows Phone Developer Tools not only ships the official Panorama & Pivot controls, it also provides project templates for new developments. Please convert your existing projects to these new controls.

The good news is that the programming model between both is pretty close, so the conversion effort should be very limited. This page documents few tricks to help you out.

Fix your project structure

1. Delete your dependencies on the Phone.Controls.Samples project
   
   • Remove the Phone.Controls.Samples project from your solution
   • Delete the reference to the Phone.Controls.Samples assembly

   

2. Reference the official Microsoft.Phone.Controls assembly

   

3. Fix your XAML references:
   
   Replace: xmlns:phone="clr-namespace:Phone.Controls.Samples;assembly=Phone.Controls.Samples"
   With: xmlns:phone="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls"
    
4. Fix your code references:
   
   Replace: using Microsoft.Phone.Controls;
   With: using Phone.Controls.Samples;
    
5. Other dependencies
   
   If you rely on the PivotItemCollectionAdaptor helper for databinding, don’t forget to copy the source file over to your project.

Changes in Pivot control 

• Control name : changed from PivotControl to Pivot.
   
• Pivot.SelectedItem type : changed from PivotItem to object. You’ll need to add an explicit cast in your code.
   
• PivotItem.Title : removed.
  
  The official Pivot control doesn’t have a concept of Title for the PivotItem. It only implements the Header. Because of this, it will not automatically update the Pivot’s Title during a selection change.
  If you rely on this feature, you can implement the Title updates in the SelectionChanged event.

Changes in Panorama control

• Control Name : changed from PanoramaControl to Panorama.
   
• Panorama.SelectedItem type : changed from PanoramaItem to object. You’ll need to add an explicit cast in your code.
   
• Panorama.BackgroundImage : removed. Use a ImageBrush on the Background property instead. Here’s an example:
  
  <phone:Panorama x:Name="panorama1" 
                                    Title=”pictures”>
      <phone:Panorama.Background>
          <ImageBrush ImageSource="/PictureViewer;component/Resources/panorama.jpg" /> 
      <phone:Panorama.Background>
   
• Panorama.SelectedIndex : readonly.
• Panorama.SelectedItem : readonly.
  
  Navigation in panoramic views is controlled by the user. Programmatic changes of the selected section are confusing and not allowed : Panorama is not suited for “wizard” type of UX.
  However, if you need to set the default section when returning from a tombstoned state, you can use the Panorama.DefaultItem property.
   
• PanoramaItem.Width : didn’t change, you can still fix the section’s width. However, you will need to set PanoramaItem.Orientation=”Horizontal” if you want a larger section.
   
• PanoramaItem.AutoSnap : removed. The behavior is enforced, similar to AutoSnap=”False”.