Just about every application needs controls, such as buttons, text boxes, and drop-down lists. Silverlight controls are designed to work similar to one another. You typically use the following pattern with working with controls:

This QuickStart shows you where you can get controls. It also show you how use controls by either writing code or by using the Silverlight Designer for Visual Studio.

This QuickStart contains the following sections:

• Control Example
• Getting Silverlight Controls
• Adding a Control to a Silverlight Application
• Setting Control Properties
• Creating an Event Handler

Control Example

The following example shows a TextBox control with its Text property set, and a handler associated with its TextChanged event. When you change the text, a ToolTip appears.

Getting Silverlight Controls

Silverlight controls are made available in different locations depending on their maturity. Microsoft provides Silverlight controls in the following locations:

• Silverlight runtime
• Silverlight SDK
• Silverlight Toolkit

The Silverlight runtime includes core controls that should not change, other than the addition of new features. These include the controls that are most frequently needed, such as buttons and text boxes. The Silverlight SDK includes additional controls and libraries that are at a stable development stage. Finally, there is the Silverlight Toolkit which contains binaries and source code for controls that are at various stages of development. As they mature, some controls in the Silverlight Toolkit are moved to the Silverlight SDK or the Silverlight runtime. Some controls in the Silverlight Toolkit are removed completely. Controls in the Silverlight Toolkit are categorized by quality bands that indicate their maturity in the development process. For more information about the control quality bands, see Silverlight Toolkit.

The Silverlight 3 runtime and Silverlight 3 SDK are part of Visual Studio 2010 and Visual Web Developer 2010 Express. The Silverlight 4 runtime and Silverlight 4 SDK are part of the Silverlight Tools for Visual Studio installation. With this installation, you get the Visual Studio Silverlight 4 project templates, the Silverlight 4 runtime, and the Silverlight 4 SDK. The Silverlight Toolkit is a separate installation.

Once you have installed the Silverlight Tools for Visual Studio, and the Silverlight Toolkit, you can easily locate available controls by creating a new Silverlight project and viewing controls in the Toolbox. For a list of controls that are included in the Silverlight runtime and the Silverlight SDK, see Controls and Dialog Boxes.

Silverlight controls are designed to be similar, regardless of whether they are in the runtime, Silverlight SDK or Silverlight Toolkit. In addition, most controls offer rich designer support in Visual Studio 2010 and Visual Web Developer 2010 Express.

Adding a Control to a Silverlight Application

You can add a control to a Silverlight application in several ways:

• Add the control from the Visual Studio Toolbox to the Design view or using another WYSIWYG tool like Expression Blend.
• Add the control in XAML, using the XAML view.
• Add the control in code.

The following illustration shows the Silverlight Designer for Visual Studio. When you add and manipulate controls in your application, you can use many of its features including the ToolBox, Design view, XAML view and the Properties window. For more information about the Silverlight Designer, see Silverlight Designer for Visual Studio.

To add a control to your application, double-click it in the Toolbox. You can also drag the control to Design view. The following illustration shows some of the controls in the Toolbox.

When you double-click the TextBox control, the following XAML is added to XAML view.

XAML

<Textbox Height="23" HorizontalAlignment="Left"  Margin="10,10,0,0" Name="textBox1" 
    VerticalAlignment="Top" Width="120"  />

The following code shows how to add a TextBox with the same settings in the code-behind.

C#

public MainPage()
{
    // Create the TextBox.
    TextBox textBox1 = new TextBox();

    InitializeComponent();

    // Set the properties.         
    textBox1.Height = 23;
    textBox1.HorizontalAlignment = HorizontalAlignment.Left;
    textBox1.Margin = new Thickness(10, 10, 0, 0);
    textBox1.Name = "textBox1";
    textBox1.VerticalAlignment = VerticalAlignment.Top;
    textBox1.Width = 120;

    // Add the TextBox to the visual tree.
    this.LayoutRoot.Children.Add(textBox1);
}

Visual Basic

' Create the TextBox.
Dim WithEvents textBox1 As New TextBox()

Public Sub New()
    InitializeComponent()

    ' Set the properties.
    textBox1.Height = 23
    textBox1.HorizontalAlignment = HorizontalAlignment.Left
    textBox1.Margin = New Thickness(26, 24, 0, 0)
    textBox1.Name = "textBox1"
    textBox1.VerticalAlignment = VerticalAlignment.Top
    textBox1.Width = 120
      
    ' Add the TextBox to the visual tree.
    Me.LayoutRoot.Children.Add(textBox1)

End Sub

Setting Control Properties

You use properties to change the appearance or content of controls. You can set control properties in the Properties window, in XAML or in code. For example, to display text in the TextBox, set the control's Text property. The following image shows setting the Text property in XAML. The following illustration shows how to set the Text property by using the Properties window.

The following illustration shows how to set the Text property in XAML view. Notice the IntelliSense window that appears.

The following shows the resulting XAML after the Text property is set.

XAML

<Textbox Height="23" HorizontalAlignment="Left"  Margin="10,10,0,0" Name="textBox1" 
    Text="This is a TextBox" VerticalAlignment="Top" Width="120"  />

The following example shows how to set the Text property in code.

C#

textBox1.Text = "This is a TextBox";

Visual Basic

textBox1.Text = "This is a TextBox"

Some properties, such as Width, Height or Margin, can be changed, simply by selecting and manipulating the control in Design view. The following illustration shows some of the resizing tools available in Design view.

Adding an Event Handler

Each control has events that enable you to respond to actions from the user. For example, a button control contains a click event that is raised when the button is clicked. You create a method, called an event handler, to handle the event. You can create an event handler in the Properties window or in XAML. You can also create an event handler manually in code, provided that you have set the name property for the control. For more information about events, see Events Overview for Silverlight.

To create an event handler using the Properties window, you select the control and then click the Events button at the top of the Properties window. The Properties window lists all of the events available for that control. The following illustration shows the Properties window when a TextBox control is selected and the Events button is clicked. To create an event handler, you double-click the event name, or you type the desired name for the event handler and press ENTER.

The following illustration shows how to create an event handler for the TextChanged event in XAML. Similar to setting properties, the XAML editor displays an Intellisense window when you begin typing.

When the control is declared in XAML, another option for adding an event handler is by using the Events button of the Properties window. The following image shows the Properties window when the Events button is pressed. When you use the Events button, you can either type in the desired name for the event handler, or select a preexisting event-handler from the drop-down list.

The following example shows the event handler for the TextChanged event.

 

XAML

 <Textbox Height="23" HorizontalAlignment="Left"  Margin="10,10,0,0" Name="textBox1" 
       Text="This is a TextBox" VerticalAlignment="Top"
       TextChanged="textBox1_TextChanged" Width="120"  />

You can also associate an event with its handler in code-behind. The following code shows how to do this in C#.

C#

textBox1.TextChanged +=new TextChangedEventHandler(textBox1_TextChanged);

For Visual Basic, you should add the Handles keyword and the event name to the signature of the handler method. This is shown in the following example.

Visual Basic

Private Sub textBox1_TextChanged(ByVal sender As Object, _
    ByVal e As TextChangedEventArgs) _
    Handles textBox1.TextChanged

The following code shows the handler for the TextChanged event with an implementation added.

C#

ToolTip toolTip1 = new ToolTip();

private void textBox1_TextChanged(object sender, TextChangedEventArgs e)
{
      if (!toolTip1.IsOpen)
          toolTip1.PlacementTarget = textBox1;
          toolTip1.Content = "You changed the text!";
          toolTip1.IsOpen = true;
}

Visual Basic

 Private toolTip1 As New ToolTip()
    Private Sub textBox1_TextChanged(ByVal sender As Object, _
    ByVal e As TextChangedEventArgs) 
      
        If Not toolTip1.IsOpen Then
            toolTip1.PlacementTarget = textBox1
        End If
        toolTip1.Content = "You changed the text!"
        toolTip1.IsOpen = True
    End Subb

What's Next

You now know the basics of adding a control to your application, setting control properties, and creating event handlers. Next, you'll learn more about which controls can be used for a given purpose: Controls 2; Choosing Controls and Adding Content.

See Also

• Controls by Function
• Getting Started with Controls
• Silverlight Designer for Visual Studio
• Using Controls and Dialog Boxes
• Silverlight Toolkit