Controls for Windows Phone 8

Artigo
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

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.

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

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

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.

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.

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. Note: 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.

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

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.

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

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

Compartilhar via

Controls for Windows Phone 8

Navigation controls