Types of Controls

Silverlight quickstart for Windows Phone development

There are several different types of controls that you can use in your Silverlight for Windows Phone applications. Some of these controls are available for Silverlight desktop applications and some controls are available for Windows Phone applications only. This QuickStart categorizes the different types of controls available for Silverlight for Windows Phone applications and details how to add content to those controls.

This QuickStart 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
• Toolkit Controls

Navigation Controls

Silverlight for Windows Phone applications are based on a page model in which users navigate forward through different pages of content. This model is based on one application 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 for Windows Phone. The following table lists controls used to provide navigation for Windows Phone applications.

Control	Location	Notes
PhoneApplicationFrame	Microsoft.Phone assembly	The main control of the Silverlight for Windows Phone application. 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 application 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 application, 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 application will support landscape or portrait orientation when choosing the layout controls for your application. For more information about orientation, see the Screen Orientations QuickStart.

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 applications. The Pivot and Panorama controls derive from ItemsControl and were created specifically for use in Silverlight for Windows Phone applications. 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 applications.

Control	Location	Notes
Border	Silverlight System.Windows assembly	Provides a border, a background, or both to another control.
Canvas	Silverlight System.Windows assembly	Provides a surface to display child elements at specific coordinates in the canvas.
ContentControl	Silverlight 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	Silverlight 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. Silverlight for Windows Phone only.
Pivot	Microsoft.Phone.Controls assembly	Provides a quick way to manage the views of large sets of data within an application. The control can be used as a navigation interface for filtering large sets or switching between views. Silverlight for Windows Phone only.
StackPanel	Silverlight System.Windows assembly	Provides a surface to display child elements in a line; either horizontally or vertically.
VirtualizingStackPanel	Silverlight 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	Silverlight System.Windows assembly	Provides a scrollable surface for displaying a child element.

For more information about Silverlight layout controls and the layout system, see the Layout QuickStart. For more information about the Pivot and Panorama controls, see Pivot Control Overview and Panorama Control Overview.

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 Text QuickStart. The following table lists the text controls for Windows Phone applications.

Control	Location	Notes
TextBlock	Silverlight System.Windows assembly	Use this to display simple, read-only snippets of text. Content is set with the Text property.
TextBox	Silverlight 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	Silverlight 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 application. 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	Silverlight System.Windows assembly	A control that responds to user input and raises a Click event. Content is set with Content property.
HyperlinkButton	Silverlight 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 application, or a web page that is external to the current application. 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	Silverlight 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	Silverlight 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	Silverlight 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. For more options for displaying a list of items, see the Toolkit Controls section later in this QuickStart.

Control	Location	Notes
ListBox	Silverlight 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.

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 applications. The following table lists controls to display resources such as images, maps, and media files.

Control	Location	Notes
Image	Silverlight System.Windows assembly	Displays an image. Content is set with the Source property. Windows Phone applications support PNG and JPG image formats.
Map	Bing assembly	Displays a Bing map. You can drag the control from the Toolbox to your application, but for the control to display properly at runtime, you must obtain a Bing Maps Key for your application. 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	Silverlight 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 application. 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 applications. There are differences between the WebBrowser control for Silverlight and the WebBrowser control for Windows Phone. For more information, see Differences Between the Desktop and Device WebBrowser Controls for Windows Phone. 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.

WebBrowser Control

The following image shows the WebBrowser control displaying content.

Progress and Message Controls

A well-designed application 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	Silverlight 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 application. Microsoft has an unsupported alternative named PerformanceProgressBar.
Popup	Silverlight 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.

Toolkit Controls

You can find additional controls in the Silverlight for Windows Phone Toolkit on CodePlex. The site includes the controls, source code, and samples. The following table lists the controls that are currently in the toolkit. The toolkit also contains additional components, such as page transitions and a gesture service.

Control	Location	Notes
AutoCompleteBox	Microsoft.Phone.Controls.Toolkit assembly	Represents a control that provides a text box for user input and a drop-down that contains possible matches based on the input in the text box. Very similar to the AutoCompleteBox control for Silverlight.
ListPicker	Microsoft.Phone.Controls.Toolkit assembly	Combines a text box that displays the currently selected item with a drop-down list of values a user can select from.
LongListSelector	Microsoft.Phone.Controls.Toolkit assembly	Provides an advanced list box that supports item grouping and virtualization.
ContextMenu	Microsoft.Phone.Controls.Toolkit assembly	Provides an in-position menu. Use to provide a menu when a user touches and holds a control.
DatePicker	Microsoft.Phone.Controls.Toolkit assembly	Allows the user to select a date.
TimePicker	Microsoft.Phone.Controls.Toolkit assembly	Allows the user to select a time.
ToggleSwitch	Microsoft.Phone.Controls.Toolkit assembly	Provides a label and an on/off setting.
WrapPanel	Microsoft.Phone.Controls.Toolkit assembly	Provides a layout control that positions child elements sequentially until there is insufficient space, and then it provides a new row for child items. The child items wrap to the next row.

See Also

• Using Controls QuickStart
• Controls for Windows Phone
• Control Content Models
• Getting Started with Controls
• Silverlight Designer for Visual Studio