Provides the base class for defining a new control that encapsulates related existing controls and provides its own logic.
(in System.Windows.dll)
Visual Basic (Declaration)
<ContentPropertyAttribute("Content", True)> _
Public Class UserControl _
Inherits Control
Dim instance As UserControl
[ContentPropertyAttribute("Content", true)]
public class UserControl : Control
XAML Object Element Usage
<UserControl ...>
singleContentElement
</UserControl>
-or-
<UserControl .../>
XAML Values
- singleContentElement
Exactly one object element for a class that derives from UIElement. This is almost always an object that can take child elements (such as a Panel) so that multiple elements can be added to content. XAML processing of a UserControl has a special behavior that sets this content to the otherwise protected Content property.
When you create a Silverlight project in Microsoft Visual Studio 2008, the new project creates a class that inherits from UserControl. The UserControl is a logical choice as the base class for a Silverlight-based application because the UserControl meets all the requirements necessary.
Two other primary reasons for creating a control that inherits from UserControl are 1) to separate functionality into smaller, manageable pieces of logic that can be created independently from an application and other controls; 2) to group related controls that can be used more than once in an application.
A UserControl is a composite of existing elements. You add elements to a UserControl by setting the Content property. Since Content is a single UIElement, you typically set it to an element that inherits from the Panel class and populate the Children of the Panel. The Content property is protected so that developers who use your control cannot change its purpose.
It is typical to put a UserControl inside of another UserControl. When you create a UserControl that encapsulates a piece of logic, you will usually place that UserControl as the root element of your Silverlight-based application, which is another UserControl.
Although the UserControl inherits the template property from the Control class, you cannot apply a ControlTemplate to a UserControl. To create a control that uses a ControlTemplate, see Creating a New Control by Creating a ControlTemplate.
The following examples demonstrate creating a UserControl and using it multiple times in a Silverlight-based application. This first example creates a UserControl called NameReporter that asks for a name of a person, and reports it back to the user. NameReporter has several TextBlock controls, two TextBox controls, and a Button. The user enters a first and last name into the appropriate TextBox, and then clicks the button. The control then displays a message box with the name that the user entered.
<UserControl x:Class="UserControlExample.NameReporter"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" >
<StackPanel HorizontalAlignment="Center">
<StackPanel.Resources>
<!--Create a Style for a TextBlock.-->
<Style TargetType="TextBlock" x:Key="TextBlockStyle">
<Setter Property="Foreground" Value="Navy"/>
<Setter Property="FontSize" Value="14"/>
<Setter Property="VerticalAlignment" Value="Bottom"/>
</Style>
<!--Create a Style for a TextBlock.-->
<Style TargetType="TextBox" x:Key="TextBoxStyle">
<Setter Property="Width" Value="200"/>
<Setter Property="Height" Value="30"/>
<Setter Property="Margin" Value="4"/>
<Setter Property="FontSize" Value="14"/>
<Setter Property="Background" Value="Blue"/>
</Style>
</StackPanel.Resources>
<TextBlock FontSize="18" Text="Enter your name."/>
<StackPanel Orientation="Horizontal">
<TextBlock Style="{StaticResource TextBlockStyle}">
First Name:
</TextBlock>
<TextBox Name="firstName" Style="{StaticResource TextBoxStyle}"/>
</StackPanel>
<StackPanel Orientation="Horizontal">
<TextBlock Style="{StaticResource TextBlockStyle}">
Last Name:
</TextBlock>
<TextBox Name="lastName" Style="{StaticResource TextBoxStyle}"
Margin="6,4,4,4"/>
</StackPanel>
<Button Width="50" Content="Submit" Click="Button_Click"/>
</StackPanel>
</UserControl>
Imports System.Text
Imports System.Windows
Imports System.Windows.Controls
Partial Public Class NameReporter
Inherits UserControl
Public Sub New()
InitializeComponent()
End Sub
Private Sub Button_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
Dim displayText As New StringBuilder("Hello, ")
'displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text)
MessageBox.Show(displayText.ToString())
End Sub
End Class
using System.Text;
using System.Windows;
using System.Windows.Controls;
namespace UserControlExample
{
public partial class NameReporter : UserControl
{
public NameReporter()
{
InitializeComponent();
}
private void Button_Click(object sender, RoutedEventArgs e)
{
StringBuilder displayText = new StringBuilder("Hello, ");
displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text);
MessageBox.Show(displayText.ToString());
}
}
}
The following example places two NameReporter controls in a Grid. Each control is self-contained and reports only the name entered in its textboxes.
Run this sample
<Grid xmlns:src="clr-namespace:UserControlExample"
Background="White" Margin="0,50,0,0">
<Grid.RowDefinitions>
<RowDefinition Height="Auto"/>
<RowDefinition Height="Auto"/>
</Grid.RowDefinitions>
<src:NameReporter Grid.Row="0"/>
<src:NameReporter Grid.Row="1" Margin="0,15,0,0"/>
</Grid>
System..::.Object
System.Windows..::.DependencyObject
System.Windows..::.UIElement
System.Windows..::.FrameworkElement
System.Windows.Controls..::.Control
System.Windows.Controls..::.UserControl
System.Windows.Controls..::.Page
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
Reference