Quickstart: Types of controls for Windows Phone

Article
07/09/2012

[This documentation is preliminary and is subject to change.]

July 09, 2012

Applies to: Windows Phone 8 Developer Preview | Windows Phone OS 7.1

There are several different types of controls that you can use in your Windows Phone apps. This Quickstart categorizes the different types of controls available for Windows Phone apps and details how to add content to those controls.

This topic contains the following sections.

Navigation controls
Layout and grouping controls
Text controls
Button and selection controls
List controls
Image, map, and media controls
HTML controls
Progress and message controls
Related Topics

Windows Phone apps are based on a page model in which users navigate forward through different pages of content . This model is based on one app frame control that contains page controls for users to navigate through. Pages contain layout controls, which in turn contain additional controls. For more information about frame and page navigation, see Frame and Page Navigation Overview. The following table lists controls used to provide navigation for Windows Phone apps.

Control	Location	Notes
PhoneApplicationFrame	Microsoft.Phone assembly	The main control of the Windows Phone app. This control supports navigation to and from pages.
PhoneApplicationPage	Microsoft.Phone assembly	Encapsulates content that can be navigated to by PhoneApplicationFrame.

The following image shows the frame and page model.

Controls - Frame Page

Layout and grouping controls

Controls that contain other controls are often referred to as layout controls. Layout controls are containers for other controls and visual objects. As the name implies, layout controls are used to position these contained objects on the screen. A layout control serves as the layout root of your app within a page. All other objects in your UI are contained in this root. You can use additional layout controls inside the layout root as needed. When you create a new Windows Phone app, a Grid control that serves as the layout root is created. The layout root contains additional layout controls that serve as the title panel and content panel. You'll add additional layout controls to the content panel. Additionally, you should consider whether your app will support landscape or portrait orientation when choosing the layout controls for your app. For more information about orientation, see the Quickstart: Screen orientation for Windows Phone.

Most layout controls derive from the Panel class. Some examples of layout controls that derive from panel are StackPanel, Canvas, and Grid. There are two additional controls, Panorama and Pivot, which you can use to lay out phone apps. The Pivot and Panorama controls derive from ItemsControl and were created specifically for use in Windows Phone apps. These controls are different than typical items controls because they should contain a small number of items, versus a typical items control that can contain a large list. These controls allow users to easily swipe and pan between their items.

The following table lists controls that are used for layout and element grouping in Windows Phone apps.

Control	Location	Notes
Border	System.Windows assembly	Provides a border, a background, or both to another control.
Canvas	System.Windows assembly	Provides a surface to display child elements at specific coordinates in the canvas.
ContentControl	System.Windows assembly	Represents a container control with a single child element. The child element is an object, so the child can contain a layout control with additional child elements.
Grid	System.Windows assembly	Provides a surface composed of rows and columns to display child elements. You define the rows and columns for a grid, then assign objects to a specific row or column in the grid.
Panorama	Microsoft.Phone.Controls assembly	Creates a panoramic view of items that can be panned side-to-side.
Pivot	Microsoft.Phone.Controls assembly	Provides a quick way to manage the views of large sets of data within an app. The control can be used as a navigation interface for filtering large sets or switching between views.
StackPanel	System.Windows assembly	Provides a surface to display child elements in a line; either horizontally or vertically.
VirtualizingStackPanel	System.Windows assembly	Provides a stack panel control that arranges content that is visible on the screen, creating additional UI items as needed. VirtualizingStackPanel has better performance than StackPanel when working with a large set of items.
ScrollViewer	System.Windows assembly	Provides a scrollable surface for displaying a child element.

For more information about Windows Phone layout controls and the layout system, see the Quickstart: Layout for Windows Phone. For more information about the Pivot and Panorama controls, see Quickstart: Panorama and Pivot controls for Windows Phone.

The following image shows some of the layout controls used in both portrait and landscape orientation. In this image, a StackPanel and a Canvas are nested in a Grid, which uses the column and row-based layout system.

Controls - Layout Controls

The following image shows the Panorama control and how it can be used to present a view on horizontal content.

Controls - Panorama

Text controls

Text controls typically display string content. There are different types of text controls for different purposes. For more information, see the Quickstart: Text for Windows Phone. The following table lists the text controls for Windows Phone apps.

Control	Location	Notes
TextBlock	System.Windows assembly	Use this to display simple, read-only snippets of text. Content is set with the Text property.
TextBox	System.Windows assembly	Typically used for short text input. However, you can also use it for larger, multi-line text input. Content is set with the Text property.
PasswordBox	System.Windows assembly	Masks the text a user inputs. Content is set with the Password property and masked with the PasswordChar property.

The following image shows the text controls.

Controls - Text Controls

Button and selection controls

Button and selection controls enable the user to easily choose items or navigate through the app. Most button and selection controls derive from ContentControl, which means you add content to them with the Content property. The Content property is of type Object, so there are few restrictions on what a content control can contain. Because many classes that derive from Object can contain other controls, you can create nested content in a ContentControl. For example, you can set the Content property of a button to a StackPanel that contains an image and text. The following table lists the button controls.

Control	Location	Notes
Button	System.Windows assembly	A control that responds to user input and raises a Click event. Content is set with Content property.
HyperlinkButton	System.Windows assembly	Represents a button control that displays a hyperlink. When clicked, the HyperlinkButton enables users to move to a web page in the same web app, or a web page that is external to the current app. Content is set with the Content property and the URL to navigate to is set with the NavigateUri property.

The following table lists controls that the user can use to specify selections.

Control	Location	Notes
CheckBox	System.Windows assembly	Represents a control that a user can select or clear. A check box optionally offers an indeterminate state. Content is set with the Content property.
RadioButton	System.Windows assembly	Allows a user to select a single option from a list of options. When radio buttons are grouped together they are mutually exclusive. Content is set with the Content property.
Slider	System.Windows assembly	Represents a control that lets the user select from a range of values along a track. The Value property determines the position on the track.

The following image shows the button and selection controls.

Controls - Button Selection

List controls

The following table lists the control that you can use to display a list of items.

Control	Location	Notes
ListBox	System.Windows assembly	Displays a list of items a user can select by clicking. Content is set with the Items or ItemsSource property. The look of each item can be customized by using a DataTemplate.
LongListSelector	Microsoft.Phone assembly	Use to group, display, and scroll through long lists of data. You can scroll to a specific item in a list using the ScrollTo property or to a group in the list using the ScrollToGroup property.

The following image shows the ListBox control displaying a list of items.

Controls - List Controls

Image, map, and media controls

Displaying resources, such as images, maps, and media content is an important part of building a rich user interface for Windows Phone apps. The following table lists controls to display resources such as images, maps, and media files.

Control	Location	Notes
Image	System.Windows assembly	Displays an image. Content is set with the Source property. Windows Phone apps support PNG and JPG image formats.
Map	Bing assembly	Displays a Bing map. You can drag the control from the Toolbox to your app, but for the control to display properly at runtime, you must obtain a Bing Maps Key for your app. For more information, see Getting a Bing Maps Key. You set the type of map displayed by using the Mode property, and control how the map is zoomed by using the ZoomLevel property.
MediaElement	System.Windows assembly	Use this control to play audio and video. Content is set with the Source property. For performance reasons, you shouldn't use this control to play sound effects in your app. It's better to use the XNA Framework SoundEffect class instead.

The following image shows the Image, Map, and MediaElement controls displaying content.

Controls - Image Map Media Controls

HTML controls

You can use the WebBrowser control to display HTML in your apps. The following table lists the control for displaying HTML.

Control	Location	Notes
WebBrowser	Microsoft.Phone.Controls assembly	Displays rendered HTML. Content is set with the Source property.

The following image shows the WebBrowser control displaying content.

Controls - Web Browser Control

Progress and message controls

A well-designed app provides feedback to the user, such as progress for a long operation or a message indicating an error has occurred. The following table lists controls you can use to display progress and messages to the user.

Control	Location	Notes
ProgressBar	System.Windows assembly	Displays the current progress of an operation to the user. You can use this control to report the specific progress of an operation, or simply to indicate progress in indeterminate mode. Using this control in indeterminate mode can decrease the performance of your app. Microsoft has an unsupported alternative named PerformanceProgressBar.
Popup	System.Windows assembly	Displays content as an overlay over existing content. This is useful for temporarily displaying content that accomplishes a specific task. Typically, you create a UserControl and set it as the Child property of the Popup. Set the IsOpen property to true to display the Popup control. A less-flexible alternative to the Popup control is the MessageBox component.

ProgressBar

System.Windows assembly

Displays the current progress of an operation to the user. You can use this control to report the specific progress of an operation, or simply to indicate progress in indeterminate mode. Using this control in indeterminate mode can decrease the performance of your app. Microsoft has an unsupported alternative named PerformanceProgressBar.

Popup

System.Windows assembly

Displays content as an overlay over existing content. This is useful for temporarily displaying content that accomplishes a specific task. Typically, you create a UserControl and set it as the Child property of the Popup. Set the IsOpen property to true to display the Popup control.

A less-flexible alternative to the Popup control is the MessageBox component.

The following image shows a Popup control that contains a TextBlock, a Button, and a ProgressBar in its regular and indeterminate mode.

Controls - Popup Progress

Quickstart: Types of controls for Windows Phone

Navigation controls