Control Content Models
Microsoft Silverlight will reach end of support after October 2021. Learn more.
In Silverlight, controls are designed to display certain kinds of content. In order to choose which control to use or derive your control from, it is important to understand what kinds of objects a particular control can best display. There are several types of controls that display arbitrary content in Silverlight.
Text Controls
Controls that Display a Single Element
Controls that Display a Single Element and a Header
Controls that Display a Collection of Items
Controls that Display a Collection of Items and a Header
Controls That Display User Interface Elements
Overview
The following table lists many of the common Silverlight controls and their corresponding content type and content property.
Control |
Content Type |
Content Property |
|---|---|---|
Text |
||
Text |
||
Text |
||
Text |
||
Text |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element |
||
Single element and a header |
||
Collection of items |
||
Collection of items |
||
Collection of items |
||
Collection of items |
||
Collection of items |
||
Collection of items |
||
Text and collection of items |
||
User interface elements |
||
User interface elements |
||
User interface elements |
Text Controls
Text controls display string content. There are three types of text controls.
These controls offer a choice between read-only text with multiple formats applied, single format editable text, and rich format editable text.
TextBlock
The TextBlock control inherits directly from FrameworkElement. It displays read-only text that can be extensively formatted. You set its content with the Text or Inlines properties. The Text property takes a String. The Inlines property takes a InlineCollection. An InlineCollection accepts Inline objects. Inline is an abstract class, so you use Run or LineBreak objects, which derive from Inline, to populate the collection. One advantage to setting the Inlines property is that you can specify the font family, style, weight, and size for each Inline in the Inlines collection. However, if you want to use the same font or font style for all the text in a TextBlock, the Text property is the easiest option.
The following example shows how to set the content of TextBlock objects by using the Text and Inlines properties in XAML and in code.
<TextBlock Margin="10" Text="TextBlock" />
...
<TextBlock Margin="10">
<Run FontFamily="Arial" FontSize="20">TextBlock</Run>
<LineBreak />
<Run FontFamily="Courier New" FontWeight="Bold" FontSize="14">using Inlines</Run>
</TextBlock>
Dim tBlock1 As New TextBlock()
tBlock1.Text = "TextBlock"
LayoutRoot.Children.Add(tBlock1)
...
Dim tBlock2 As New TextBlock()
Dim run1 As New Run()
run1.Text = "Text"
run1.FontFamily = New FontFamily("Arial")
run1.FontSize = 20
tBlock2.Inlines.Add(run1)
tBlock2.Inlines.Add(New LineBreak())
run1 = New Run()
run1.Text = "using Inlines"
run1.FontFamily = New FontFamily("Courier New")
run1.FontSize = 14
run1.FontWeight = FontWeights.Bold
tBlock2.Inlines.Add(run1)
LayoutRoot.Children.Add(tBlock2)
TextBlock tBlock1 = new TextBlock();
tBlock1.Text = "TextBlock";
LayoutRoot.Children.Add(tBlock1);
...
TextBlock tBlock2 = new TextBlock();
Run run1 = new Run();
run1.Text = "Text";
run1.FontFamily = new FontFamily("Arial");
run1.FontSize = 20.0;
tBlock2.Inlines.Add(run1);
tBlock2.Inlines.Add(new LineBreak());
run1 = new Run();
run1.Text = "using Inlines";
run1.FontFamily = new FontFamily("Courier New");
run1.FontSize = 14.0;
run1.FontWeight = FontWeights.Bold;
tBlock2.Inlines.Add(run1);
LayoutRoot.Children.Add(tBlock2);
TextBox and PasswordBox
The TextBox class inherits from Control and displays text that is editable by the user. You set the content of a TextBox by using the Text property. Formatting of the displayed text is limited to the formatting that you apply to the control, which applies to all the text it contains. You set the text to wrap by using the TextWrapping property. You specify the font style, font weight, font size and font family by using the FontStyle, FontWeight, FontSize, FontFamily properties, respectively. The property settings apply to all the text displayed by the TextBox.
PasswordBox inherits from TextBox and you set its content by using the Text property. PasswordBox allows a single line of text, and obscures the text by using a symbol. This allows users to enter sensitive data, such as passwords.
The following example shows how to set the Text property of a TextBox in XAML and in code.
<TextBox Margin="10" HorizontalAlignment="Left" Width="100"
Text="TextBox with a line of text that wraps."
FontFamily="Arial" TextWrapping="Wrap" />
Dim tBox1 As New TextBox()
tBox1.Text = "TextBox with a line of text that wraps."
tBox1.FontFamily = New FontFamily("Arial")
tBox1.TextWrapping = TextWrapping.Wrap
tBox1.Width = 100
LayoutRoot.Children.Add(tBox1)
TextBox tBox1 = new TextBox();
tBox1.Text = "TextBox with a line of text that wraps.";
tBox1.FontFamily = new FontFamily("Arial");
tBox1.TextWrapping = TextWrapping.Wrap;
tBox1.Width = 100.0;
LayoutRoot.Children.Add(tBox1);
RichTextBox
RichTextBox inherits from Control and displays rich text that is editable by the user. You set the content of a RichTextBox with the Blocks property. The Blocks property contains a collection of Paragraph elements. A Paragraph element can contain many types of elements including the following:
InlineUIContainer, which can contain FrameworkElement objects, such as an Image or a Button
For more information about RichTextBox, see RichTextBox Overview.
Controls that Display a Single Element
There are two main categories of controls that contain a single element. Controls that display resource content and controls that derive from the ContentControl class.
Resource Controls
Resource controls are controls that display images and media, such as a graphic, a video, or an HTML page. Image, MediaElement, and WebBrowser are all examples of resource controls. You set content for these controls by using the Source property. You set the Source property to an absolute or a relative URL of the resource that you want to display. A relative URL should indicate a location relative to the application (.XAP) file. The following example shows how to set the source for an Image control. In this example, myPicture.png should be in the same directory as the .XAP file.
<Image Source="myPicture.png" />
Content Controls
Content controls are any control that derives from the ContentControl class. There are many controls that derive from ContentControl. The following table lists some ContentControl examples.
Category |
ContentControl Example |
|---|---|
Button controls |
|
Toggle controls |
|
Item containers for ItemsControl |
A content control displays a single piece of content by setting its Content property. The content property is of type Object, so there are no 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 ContentControl property of a button to a StackPanel that contains an image and text. The following is an example of how to set the content property for a button in XAML and in code.
<Button Width="50">
<StackPanel Orientation="Horizontal">
<Rectangle Width="10" Fill="Green" />
<TextBlock Margin="2" Text="Green" />
</StackPanel>
</Button>
Dim button1 As New Button()
button1.Width = 50
button1.Height = 30
Dim panel1 As New StackPanel()
panel1.Orientation = Orientation.Horizontal
Dim rect1 As New Rectangle()
rect1.Width = 10
rect1.Fill = New SolidColorBrush(Colors.Green)
Dim tb3 As New TextBlock()
tb3.Margin = New Thickness(2)
tb3.Text = "Green"
tb3.TextAlignment = TextAlignment.Center
panel1.Children.Add(tb3)
panel1.Children.Add(rect1)
button1.Content = panel1
LayoutRoot.Children.Add(button1)
Button button1 = new Button();
button1.Width = 50;
button1.Height = 30;
StackPanel panel1 = new StackPanel();
panel1.Orientation = Orientation.Horizontal;
Rectangle rect1 = new Rectangle();
rect1.Width = 10;
rect1.Fill = new SolidColorBrush(Colors.Green);
TextBlock tb3 = new TextBlock();
tb3.Margin = new Thickness(2);
tb3.Text = "Green";
tb3.TextAlignment = TextAlignment.Center;
panel1.Children.Add(tb3);
panel1.Children.Add(rect1);
button1.Content = panel1;
LayoutRoot.Children.Add(button1);
Controls that Display a Single Element and a Header
TabItem is a special kind of content control that allows you to set content and a header. You set its Content property like other content controls. Additionally you can set a header for the content with the Header property. The Header property is of type Object, so like the Content property, there are no restrictions on what the header can contain. The following example shows how to set the Header and Content properties to text and a panel that contains additional content.
.gif "Note") Note: |
|---|
The TabItem is part of the Silverlight SDK and requires the following XAML namespace declaration: xmlns:sdk="https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk" |
<sdk:TabControl>
<sdk:TabItem Header="TabItem1" >
<sdk:TabItem.Content>
<StackPanel Orientation="Horizontal">
<Rectangle Width="10" Fill="Green" />
<TextBlock Margin="2" Text="TabItem1 Content" />
</StackPanel>
</sdk:TabItem.Content>
</sdk:TabItem>
<sdk:TabItem Content="TabItem 2 Content">
<sdk:TabItem.Header>
<StackPanel Orientation="Horizontal">
<Rectangle Width="10" Fill="Green" />
<TextBlock Margin="2" Text="TabItem2" />
</StackPanel>
</sdk:TabItem.Header>
</sdk:TabItem>
</sdk:TabControl>
Controls that Display a Collection of Items
There are two kinds of controls that display a collection of objects:
Items Controls
Items Controls
Items controls inherit from the ItemsControl class. The type of collection an items control can display depends on the control type and how the collection is populated. Regardless of how the content for an items control is set, each items control has an associated item container, which contain individual pieces of content in the collection. ListBox, ComboBox, TreeView, and TabControl are examples of items controls. ListBoxItem, ComboBoxItem, TreeViewItem, and TabItem are the corresponding item containers. Item containers are created for each item in a collection and can be retrieved, whether or not you create them explicitly.
There are two different properties that can determine the content for an items control.
Items Property
You can populate an items control directly by setting its Items property. The Items property is of type ItemCollection, which is a generic PresentationFrameworkCollection<T>. You can also add items to an existing collection by using the Add method. You cannot add items to a collection created by using the ItemsSource property. When you create item containers in XAML, you are adding items to the items collection. The following example shows how to create and add ComboBoxItem objects to a ComboBox in XAML and in code.
<ComboBox>
<ComboBox.Items>
<ComboBoxItem Content="Item 1" />
<ComboBoxItem Content="Item 2" />
<ComboBoxItem Content="Item 3" />
</ComboBox.Items>
</ComboBox>
Dim cb1 As New ComboBox()
cb1.Items.Add("Item 1")
cb1.Items.Add("Item 2")
cb1.Items.Add("Item 3")
LayoutRoot.Children.Add(cb1)
ComboBox cb1 = new ComboBox();
cb1.Items.Add("Item 1");
cb1.Items.Add("Item 2");
cb1.Items.Add("Item 3");
LayoutRoot.Children.Add(cb1);
ItemsSource Property
The ItemsSource property of the ItemsControl enables you to use any type that implements IEnumerable as the content of the ItemsControl. You typically use ItemsSource to display a data collection or to bind an ItemsControl to a collection object. When you set the ItemsSource property, item containers are automatically created for each item in the collection.
The following example shows how to set the ItemsSource property to a collection of Uri objects by using a combination of XAML and code.
<ComboBox x:Name="UriBox1" />
Dim Uris As New ObservableCollection(Of Uri)()
Uris.Add(New Uri("https://www.contoso.com"))
Uris.Add(New Uri("http://www.tailspintoys.com"))
Uris.Add(New Uri("http://www.cohowinery.com/"))
UriBox1.ItemsSource = Uris
ObservableCollection<Uri> Uris = new ObservableCollection<Uri>();
Uris.Add(new Uri("https://www.contoso.com"));
Uris.Add(new Uri("http://www.tailspintoys.com"));
Uris.Add(new Uri("http://www.cohowinery.com/"));
UriBox1.ItemsSource = Uris;
You can also bind to a collection by setting the ItemsSource property to a Binding object and setting the DataContext for the control. The following example shows how to set the ItemsSource to a Binding and the DataContext to the collection of Uris by using a combination of XAML and code.
<ComboBox ItemsSource="{Binding}" x:Name="UriBox2" />
Dim Uris As New ObservableCollection(Of Uri)()
Uris.Add(New Uri("https://www.contoso.com"))
Uris.Add(New Uri("http://www.tailspintoys.com"))
Uris.Add(New Uri("http://www.cohowinery.com/"))
...
UriBox2.DataContext = Uris
ObservableCollection<Uri> Uris = new ObservableCollection<Uri>();
Uris.Add(new Uri("https://www.contoso.com"));
Uris.Add(new Uri("http://www.tailspintoys.com"));
Uris.Add(new Uri("http://www.cohowinery.com/"));
...
UriBox2.DataContext = Uris;
AutoCompleteBox
AutoCompleteBox is a special control that combines a text box for user input and an items control that displays in a drop-down. The items control contains possible matches based on the input in the text box. You add content to the text portion of the control by using the Text property and you add content to the drop-down by binding to a list with the ItemsSource property.
DataGrid
The DataGrid is useful for displaying collections of data, but it is not an items control. The DataGrid control inherits directly from Control. You set its content by setting the ItemsSource property to an IEnumerable collection or a Binding, which is similar to an items control. However, you cannot populate a DataGrid control manually like an items control. When you set the ItemsSource to a collection of objects, a row is automatically created for each object in the collection. You can set the AutoGenerateColumns to true to automatically generate a column for each property of the object type. You can also specify columns yourself by using the Columns property. There are different types of columns that contain different types of content. For more information about the DataGrid control see, DataGrid.
| Note: |
|---|
The DataGrid is part of the Silverlight SDK and requires the following namespace declaration: xmlns:sdk="https://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk" |
The following example shows how to set the ItemsSource property to a collection of Uri objects by using a combination of XAML and code. The AutoGenerateColumns is set to true, so a column is automatically created for each public property of Uri.
<sdk:DataGrid x:Name="UriGrid1" AutoGenerateColumns="True" />
Dim Uris As New ObservableCollection(Of Uri)()
Uris.Add(New Uri("https://www.contoso.com"))
Uris.Add(New Uri("http://www.tailspintoys.com"))
Uris.Add(New Uri("http://www.cohowinery.com/"))
...
UriGrid1.ItemsSource = Uris
ObservableCollection<Uri> Uris = new ObservableCollection<Uri>();
Uris.Add(new Uri("https://www.contoso.com"));
Uris.Add(new Uri("http://www.tailspintoys.com"));
Uris.Add(new Uri("http://www.cohowinery.com/"));
...
UriGrid1.ItemsSource = Uris;
The following example shows how to set the ItemsSource property to a Binding object and the DataContext for the control to the collection of Uri objects by using a combination of XAML and code. The AutoGenerateColumnsProperty is set to true, so a column is automatically created for each public property of Uri.
<sdk:DataGrid ItemsSource="{Binding}" x:Name="UriGrid2" AutoGenerateColumns="True" />
Dim Uris As New ObservableCollection(Of Uri)()
Uris.Add(New Uri("https://www.contoso.com"))
Uris.Add(New Uri("http://www.tailspintoys.com"))
Uris.Add(New Uri("http://www.cohowinery.com/"))
...
UriGrid2.DataContext = Uris
ObservableCollection<Uri> Uris = new ObservableCollection<Uri>();
Uris.Add(new Uri("https://www.contoso.com"));
Uris.Add(new Uri("http://www.tailspintoys.com"));
Uris.Add(new Uri("http://www.cohowinery.com/"));
...
UriGrid2.DataContext = Uris;
Controls that Display a Collection of Items and a Header
HeaderedItemsControl is a special kind of items control that allows you to set a collection of items and a header. You set its ItemsSource property like other items controls. Additionally you can set a header for the items with the Header property. A HeaderedItemsControl is very useful for displaying hierarchical data because you can set the ItemTemplate property to a HierarchicalDataTemplate, and establish the structure for the next sublevel in a hierarchy.
Controls That Display User Interface Elements
There are several controls that derive from the Panel class and are designed for displaying user interface (UI) elements and layout. The content property for a panel-derived control is Children. The Children property is of type UIElementCollection. A UIElementCollection can only contain UIElement objects. Therefore, panels have a more restricted content model than content controls. Panel and controls that derive from Panel, Grid, Canvas and StackPanel, are discussed in detail in Silverlight Layout System.