← About Jeff

Panorama and Pivot controls for Windows Phone developers

August 10, 2010

Apps in Windows Phone 7 make it easy to explore and experience information thanks to two similar navigation controls: panorama and pivot controls. We’ve made it easy for developers to build applications with these experiences by putting these Silverlight controls and associated tooling in the next release of the free developer tools (didn’t make the beta).

The controls are simple & easy to use, but I’ve seen enough rumbling on forums to know that developers are anxious to learn more about their capabilities.

9/16/2010 Update: These controls are now in the official Windows Phone developer tools (quick post by me, but you really want to download here).

In this post I’m going to introduce these controls and how they appear from a simple API & XAML perspective.


Panorama control inside of the Visual Studio design surface for the Windows Phone 7.

Learning about the native experience

Since phones are just beginning to trickle out, if you’d like to see what the built-in applications look like, there’s some multimedia up at WindowsPhone7.com.

A panorama powers the people, music + videos, parts of Office, and more. Many of these have a large background and can be explored by panning and flicking between items. When you’re at one item, you will be able to see a little bit of the next item as well – a hint that there’s more to be explored. When you reach the far side of the panorama, you can keep going to wrap around to the beginning again, saving time.

A pivot control powers the e-mail and calendar pages, operating systems, etc. The top of the pivot control shows the headers for all the different items, and you can swipe and pan between the pages. Just like panorama, the control wraps infinitely – so when you reach the final item, instead of having to flick all the way back to the first item, you can just flick once more.

Key Features

Both of the controls are lightweight enough to have great performance, while visually engaging and responsive to touch. Some features:

  • Simple XAML and application programming interfaces
  • Standard items controls that feels natural to developers, individual items are built from PanoramaItem and PivotItem content controls
  • Complete data binding support, content template properties and item container styles
  • Automatic support for light and dark phone themes
  • Built-in touch navigation: flicks move quickly, while panning past a threshold and releasing the touch will snap to the next item
  • Beautiful easing animations for sliding during navigation
  • Extensibility offered through events, visual states, and the ability to re-template
  • Great tooling comes standard, including app and page templates

So let’s take a look at the two controls!

Panorama


A visual depiction of the actual contents of the panorama control stretching beyond the physical size of the screen.

From the UI design and interaction guide for Windows Phone 7, the UX folks say:

Unlike standard applications that are designed to fit within the confines of the phone screen, these applications offer a unique way to view controls, data, and services by using a long horizontal canvas that extends beyond the confines of the screen.

…

Elements of a panoramic application serve as the starting point for more detailed experiences.

…

The background image is the lowest layer and is meant to give the panorama its rich magazine-like feel. Usually a full-bleed image, the background is potentially the most visual part of the application.

As all things in design go, what is not on the screen is as important as what is there: the control has a lot of empty space that helps keep the eye focused on the rich experience and data.

Panorama XAML

The Panorama control is placed on pages of your application and accepts a title and a background. Panorama sections are defined by PanoramaItem controls, and each has a header. The Title and Header are easiest to use when you’re just inserting text, but they also have associated HeaderTemplate and TitleTemplate dependency properties for data binding scenarios.

<controls:Panorama
        Title="my panorama">
        <controls:Panorama.Background>
            <ImageBrush ImageSource="MyWidescreenBackground.jpg"/>
        </controls:Panorama.Background>

        <controls:PanoramaItem
            Header="first item">

            <StackPanel>
                <TextBlock
                    Text="This is a simple sample ..."
                    Style="{StaticResource PhoneTextLargeStyle}"
                    TextWrapping="Wrap"/>
            </StackPanel>

      </controls:PanoramaItem>

      <!-- insert other panorama items here in a real app -->
</controls:Panorama>

About wide horizontal sections

The panorama allows for special sections that are wider than the screen. Built-in phone hubs often use this for sets of thumbnails, albums, and other displays. If this is the appropriate effect you want for a section, make sure that the PanoramaItem declares that intent by setting the orientation to horizontal. Here’s what the minimized XAML looks like:

<controls:PanoramaItem Orientation="Horizontal">
    <!-- insert thumbnails and other goods here -->
</controls:PanoramaItem>

Panorama APIs

The key application programming interface for the Panorama builds on top of ItemsControl: so you get the standard items control properties (Items, ItemsSource, etc.), but also additional properties for setting the header, title, and reacting to the currently selected items by the user.

Microsoft.Phone.Controls.Panorama

Dependency Properties
  • DefaultItem

    Sets the default item that moves into display. Allows your application to store the user’s most recently used panorama item to return to it later, just like the native operating system’s built-in hubs.
  • HeaderTemplate
  • SelectedIndex
  • SelectedItem
  • Title
  • TitleTemplate
Events
  • SelectionChanged

    Allows the developer to hook up to selection changes (navigations from one panorama item to another).

Microsoft.Phone.Controls.PanoramaItem

Dependency Properties
  • Header
  • HeaderTemplate
  • Orientation

    Setting the orientation to Horizontal will allow the item to be of a larger size than the control so that the user can pan and navigate within it. By default, this property is Vertical, which means that panning or flicking should instead bring you to the next panorama section.

Pivot control

The pivot control is a lot like the a tab control, but designed specifically for the phone and touch interaction. The entire pivot control (often the size of the screen and the root element on a page) can be panned, flicked, and manipulated – it’s not just about those headers (though those can be touched to navigate, too).

A simple pivot sample application running in the emulator. Notice that the phone’s theme in the emulator has been set to the light theme, and the control just works without the developer having to do anything.

From the design guidelines document:

A pivot control provides a quick way to manage views or pages within the application. This control can be used for filtering large datasets, viewing multiple data sets, or switching application views. The control places individual views horizontally next to each other, and manages the left and right navigation. Flicking or panning horizontally on the page cycles the pivot functionality.

Pivot XAML

<controls:Pivot Title="MY APPLICATION">

    <controls:PivotItem
        Header="welcome">

        <StackPanel
            Margin="20">
            <TextBlock
                TextWrapping="Wrap"
                Text=" This is a simple sample ..."
                Style="{StaticResource PhoneTextLargeStyle}">
            </TextBlock>
        </StackPanel>

    </controls:PivotItem>

    <!-- other pivot items -->
</controls:Pivot>

Pivot APIs

Microsoft.Phone.Controls.Pivot

Dependency Properties
  • HeaderTemplate

    A single data template that can be used for all headers in data binding scenarios.
  • SelectedIndex
  • SelectedItem
  • Title
  • TitleTemplate
Events
  • LoadedPivotItem
  • LoadingPivotItem
  • SelectionChanged
  • UnloadedPivotItem
  • UnloadingPivotItem

Microsoft.Phone.Controls.PivotItem

Pivot item is a simple content control and does not have any other special properties.

Visual Studio & Expression Blend Tooling

The tools are fully integrated with the design tools: if you click on an item in XAML, that item will become the one active in the design surface. There’s also an easy way to add additional items, well-defined control property editing, and so this all makes it really easy to get started building immersive apps.

Start with a complete application template

You can start off with an app powered by a panorama or pivot control: File > New Project has built-in templates for these apps.

Add New Pages

When you want to add a new Windows Phone page to your app, you can also add one that’s all ready to go with either a panoramic experience or pivot control, too. Just go to the Project menu and select Add New Item:

This makes it really easy to build out applications as quick as you can click.

Blend Assets

If you need to add either control to an existing app, in Blend you’ll find them in the Assets window, so they’re right where you’d expect to find them when you need ‘em.

Easy property editing

Key properties are easily accessible in the property editor. In this screen capture, you can see how easy it is to change an item to Horizontal mode, or to change the Header property:

Right-click, add new panorama item or pivot item

Integrated into the design surface you can also add extra items to the controls by right-clicking.

 

Visual Studio design surface

 

Expression Blend

Other notes

The controls can be found in the Microsoft.Phone.Controls namespace of the Microsoft.Phone.Controls.dll assembly, installed with the official Windows Phone Developer Tools.

As we get closer to launch, I’m sure we will have a good list of caveats and suggestions for the controls. Here are a few things that I had in mind that I wanted to share ahead of time, in case you are designing your application experiences and pages today.

Exposing scrolling data

If you look at applications on the phone such as Mail, you’ll often see that the Pivot control is used to filter and sort data. So when you move to the “unread” pivot item, you have unread mail items; flicking your finger again, you’ll get to “flagged”, listing the messages that you have flagged.

You could easily have hundreds of items in a single pivot item.

If you want to enable scrolling, you must either use a scrolling control like ListBox, or add a ScrollViewer to the pivot or panorama item. Scrolling is not enabled by default. This helps ensure that items are always sized to the parent container like you’d expect in the Silverlight-powered layout system.

Here’s how to add a scroll viewer or list box to a pivot item. Note that you’ll only want to offer a vertical scrolling experience, since horizontal manipulations (pan or flick) are part of the navigation experience with these two controls.

<controls:Pivot Grid.Row="0"
                x:Name="Pivot1"
                Title="INBOX">
    <controls:PivotItem
        Header="all">
        <ListBox 
            ItemTemplate="{StaticResource MyMailDataTemplate}"
            ItemsSource="{Binding Items}">
        </ListBox>
    </controls:PivotItem>

    <controls:PivotItem
        Header="unread">
        <ScrollViewer
            ScrollViewer.HorizontalScrollBarVisibility="Disabled">
            <!-- Some large vertical list here -->
        </ScrollViewer>
    </controls:PivotItem>
</controls:Pivot>

The example uses data binding to the data context, as well as custom-defined data templates from the application’s resources, so don’t just paste it into your app… but you get the idea I hope.

Items control API

These controls do both derive from ItemsControl, but they do have subtle differences.

Both controls

  • Items can be added in XAML
  • Items can be added in code, Items.Add(new PivotItem(…)) or Items.Add(new PanoramaItem(…))
  • ItemsSource can be used for data binding
  • Do not support alternative types of items: Pivot controls must use PivotItem, Panorama must have PanoramaItem

Differences

  • Panorama exposes a DefaultItem property
  • SelectedIndex and SelectedItem are settable in Pivot but not in Panorama

Migration

There are a number of alternative implementations of these controls out there, so for release, we’ll be working to blog guidance on migrating from one of those other experiences to these controls if you would like to. Note that the http://phone.codeplex.com/ controls *are not official* and you should probably consider using these instead now that the tools are public.