Controls for Windows Phone 8

August 19, 2014

Applies to: Windows Phone 8 and Windows Phone Silverlight 8.1 | Windows Phone OS 7.1

There are several different types of controls that you can use in your Windows Phone apps. This topic 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.

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 In-app navigation for Windows Phone 8. 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

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 8.

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 Layout for Windows Phone 8.

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 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 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

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.

NoteNote:
The ListBox control does not display in the Toolbox if you are working in a Windows Phone 8 project. You can use the ListBox control in Windows Phone 8 apps, but the LongListSelector control is the recommended control for displaying lists of items.

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 method.

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

Controls - List 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

Microsoft.Phone.Maps assembly

Displays a map. You can drag the control from the Toolbox to your app, but for the control to display properly at runtime, you must obtain an ApplicationID and AuthenticationToken for your app. For more info, see How to add a Map control to a page in Windows Phone 8. You control how the map is centered and zoomed by using the Center and ZoomLevel properties.

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

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

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.

Windows Phone OS 7.1 Windows Phone OS 7.1:  Using this control in indeterminate mode in apps that target Windows Phone OS 7.1 can decrease the performance of the app. Microsoft has an unsupported alternative named PerformanceProgressBar. For more information, see Adding a custom indeterminate progress bar.

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

Show:
© 2014 Microsoft