UserControl Class (System.Windows.Controls)

Switch View

Collapse All

Language Filter

This page is specific to

Microsoft Silverlight 3

Other versions are also available for the following:

.NET Framework Class Library for Silverlight

UserControl Class

Provides the base class for defining a new control that encapsulates related existing controls and provides its own logic.

Namespace: System.Windows.Controls
Assembly: System.Windows (in System.Windows.dll)

Syntax

Visual Basic (Declaration)

<ContentPropertyAttribute("Content", True)> _
Public Class UserControl _
    Inherits Control

Visual Basic (Usage)

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.

Remarks

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.

Examples

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.

XAML

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

Visual Basic

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

XAML

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

Inheritance Hierarchy

System..::.Object
  System.Windows..::.DependencyObject
    System.Windows..::.UIElement
      System.Windows..::.FrameworkElement
        System.Windows.Controls..::.Control
          System.Windows.Controls..::.UserControl
            System.Windows.Controls..::.Page

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Reference

UserControl Members

System.Windows.Controls Namespace