Panorama and Pivot Controls

Silverlight quickstart for Windows Phone development

Windows Phone includes Panorama and Pivot controls to display related content that users can navigate horizontally. This QuickStart provides an overview of the Panorama and Pivot controls, describes how to use these controls, and provides some best practices.

This QuickStart contains the following sections:

• Panorama Control
• Pivot Control
• Choosing between Panorama and Pivot Controls
• Adding a Panorama or Pivot Control to your Project
• Panorama Control Example
• Pivot Control Example
• Best Practices

---

Panorama Control

The Panorama control is used to display related content on a long horizontal canvas that extends beyond the confines of the screen. Sections in the Panorama control, called panorama items, serve as a starting point for more detailed experiences. You can explore these items by panning and flicking between them. When you are on one item, you will be able to see a little bit of the next item, which gives you a hint that there is more to be explored. When you reach the end of the Panorama, you can keep panning to wrap around to the beginning. The Panorama control comes with built-in support for touch and navigation. You do not have to implement any special gesture functionality in Panorama control as it is enabled by default.

The people and music+videos hubs are examples of built-in experiences in Windows Phone that use the Panorama control. The following illustration shows the Panorama control for the people hub.

---

Pivot Control

The Pivot control is used for filtering large data sets, viewing multiple data sets, or switching between different views of the same data. The Pivot control is similar to a tab control, but is designed specifically for the phone and touch interaction. It places individual views horizontally next to each other so that you can navigate through these views by using the built-in pan and touch gestures.

The e-mail and calendar applications in Windows Phone are examples that use the Pivot control. The following illustration shows the Pivot control in the e-mail application.

---

Choosing Between Panorama and Pivot Control

Although Panorama and Pivot controls may seem to be similar, you should be careful in deciding when to use a Panorama and when to use a Pivot.

Use a Panorama control to enable users to explore content and to provide an entry point for further action. A Panorama control is great at aggregating information from multiple sources. A Panorama control should not provide the standalone interaction of an application. It should encourage further navigation to task-specific features that complete the whole user experience.

Use a Pivot control to enables users to filter, sort, or organize content within your application. The Pivot control should only be used to display items or data of similar type. The titles in the Pivot control should be natural categories of the data. The left-to-right navigational model in the Pivot control will help users to efficiently find the information that they need.

---

Adding a Panorama or Pivot Control to your Project

You can add a Panorama or a Pivot control to your Windows Phone project in one of the three following ways.

• By using the Toolbox

  To add a Panorama or a Pivot control to an existing page, you can drag it from the Toolbox. The Panorama and Pivot controls are not in the Toolbox by default. To add items to your Toolbox, right-click the Toolbox and then select Choose Items.

  
  

  

• By using a page template

  To add a Panorama or a Pivot control in a new page, you can use the page templates. Right-click the project in Solution Explorer, click Add, and then click New Item. In the Add New Items dialog box, select Windows Phone Panorama Page or Windows Phone Pivot Page. For more information see, How to: Create a Panorama Application for Windows Phone and How to: Create a Pivot Application for Windows Phone.

  
  

  

• By using a project template

  To start with a Panorama or a Pivot control in a new project, you can use the project templates. In the New Project dialog box, select Windows Phone Panorama Application or Windows Phone Pivot Application. The templates come pre-populated with content that you can modify.

  
  

  

When you add the Panorama and Pivot controls using one of these three ways, a reference is added to the following assembly.

• Microsoft.Phone.Controls.dll

Also, the following XML namespace is added to the page.

• xmlns:controls="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls"

---

Panorama Control Example

The following example creates a Panorama control with an image background and three PanoramaItem controls. The recommended dimensions for a background image is a height of 800 pixels and a width less than 2000 pixels. PanoramaItem controls are used to add individual sections of content to the Panorama control. A Panorama control can support multiple PanoramaItem controls and the user can navigate through these sections by using the built-in pan and touch gestures.

 

 

 

XAML

<Grid x:Name="LayoutRoot" Background="Transparent">

<!--Panorama Control-->

<controls:Panorama Title="my pictures">

<controls:Panorama.Background>

<ImageBrush ImageSource="PanoramaBackground.png" />

</controls:Panorama.Background>

<!--Panorama item one-->

<controls:PanoramaItem>

<TextBlock FontSize="30" Text="This example demonstrates

the Panorama control in a Windows Phone application." TextWrapping="Wrap" />

</controls:PanoramaItem>

<!--Panorama item two-->

<controls:PanoramaItem>

<ListBox FontSize="35">

<ListBoxItem Content="all" />

<ListBoxItem Content="recent" />

<ListBoxItem Content="favorites" />

</ListBox>

</controls:PanoramaItem>

<!--Panorama item three-->

<controls:PanoramaItem Orientation="Horizontal">

<Grid>

<Grid HorizontalAlignment="Center" VerticalAlignment="Center">

<Grid.RowDefinitions>

...

</Grid.RowDefinitions>

<Grid.ColumnDefinitions>

...

</Grid.ColumnDefinitions>

<Image Source="Creek.jpg" Grid.Row="0" Grid.Column="0"

Margin="10"/>

<Image Source="Desert.jpg" Grid.Row="0" Grid.Column="1"

Margin="10"/>

...

</Grid>

</Grid>

</controls:PanoramaItem>

</controls:Panorama>

</Grid>

The following illustration shows the results of the previous Panorama example.

• The first PanoramaItem has a TextBlock control that contains wrapped text. This is a simple way to display text in a Panorama.
• The second PanoramaItem has a ListBox control with three list items. You can scroll the list contents up or down. Vertical scrolling through a list or grid in Panorama sections is acceptable as long as it is within the confines of the section and is not in parallel with a horizontal pan.
• The third PanoramaItem has its Orientation property set to horizontal so that you can pan horizontally to view all the image thumbnails. The Panorama control allows you to display sections that are wider than the screen. You can set the Orientation property of the PanoramaItem control to horizontal so that the content that extends off the screen is not cut off and you can pan horizontally to expose the remaining content.

---

Pivot Control Example

The following example creates a Pivot control that is used to display different views of user tasks. The Pivot control has three PivotItem controls. Each PivotItem filters the tasks by all tasks, tasks for today, and tasks for tomorrow.

XAML

<!--LayoutRoot is the root grid where all page content is placed-->

<Grid x:Name="LayoutRoot" Background="Transparent">

<controls:Pivot Title="my tasks">

<!--Pivot item one-->

<controls:PivotItem Header="all">

<ListBox FontSize="30">

<ListBoxItem Content="Dentist appointment" />

<ListBoxItem Content="Pickup laundry" />

<ListBoxItem Content="Service car" />

<ListBoxItem Content="Send birthday gift to mom" />

<ListBoxItem Content="Grocery" />

</ListBox>

</controls:PivotItem>

<!--Pivot item two-->

<controls:PivotItem Header="today">

<ListBox FontSize="30">

<ListBoxItem Content="Dentist appointment" />

<ListBoxItem Content="Pickup laundry" />

</ListBox>

</controls:PivotItem>

<!--Pivot item three-->

<controls:PivotItem Header="tomorrow">

<ListBox FontSize="30">

<ListBoxItem Content="Service car" />

<ListBoxItem Content="Send birthday gift to mom" />

<ListBoxItem Content="Grocery" />

</ListBox>

</controls:PivotItem>

</controls:Pivot>

</Grid>

The following illustration shows the results of the previous Pivot example.

---

Best Practices

The following are some best practices when using a Panorama control.

• Limit the number of PanoramaItems in a Panorama control to a maximum of four. If the content is dense, or if the PanoramaItems share many controls, reduce the number of PanoramaItems.
• Hide the PanoramaItems until they have content to display by setting PanoramaItem.Visibility property to Collapsed.
• Where applicable, extend the PanoramaItems beyond the screen boundaries by setting the PanoramaItem.Orientation property to horizontal. This reinforces the panoramic nature of the control.
• Use a properly sized background image in your application. The recommended dimensions for a background image is a height of 800 pixels and a width less than 2000 pixels.
• For consistency, set the Panorama title to the same text as the launch tile in the Start screen.
• Avoid animating the Panorama title or dynamically changing its size.

The following are some best practices when using a Pivot control.

• Minimize the number of pivot items in a Pivot control for performance considerations.
• Load the contents of the Pivot control on demand as opposed to loading everything at startup.
• Use the Pivot control to display items or data of similar type.
• Do not use the Pivot control for task-based navigation, like in a wizard application.
• You should not use Application Bar buttons to provide navigation in a Pivot control. If the Pivot requires navigation aids, you are probably misusing it.

For more information about best practices for Panorama and Pivot controls, see Central Application Hub with Home Page Menu (Panorama or Pivot Control) for Windows Phone.

---

See Also

• Panorama Control for Windows Phone
• Pivot Control for Windows Phone