Compartir a través de

Quickstart: adding controls and handling events (XAML)

  • Artículo

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

You create the UI for your app by using controls such as buttons, text boxes, and combo boxes. Here we show you how to add controls to your app. You typically use this pattern when working with controls:

  • You add a control to your app UI.
  • You set properties on the control, such as width, height, or foreground color.
  • You hook up some code to the control so that it does something.

Roadmap: How does this topic relate to others? See:

Prerequisites

We assume that you can create a basic app using Microsoft Visual Basic, C#, or C++, and Extensible Application Markup Language (XAML). For instructions on creating your first app, see Create your first Windows Store app using C# or Visual Basic or Create your first Windows Store app using C++.

Adding a control

You can add a control to an app in several ways:

  • Use a design tool like Blend for Visual Studio or the Microsoft Visual Studio XAML designer.
  • Add the control to the XAML markup in the Visual Studio XAML editor.
  • Add the control in code. Controls that you add in code are visible when the app runs, but are not visible in the Visual Studio XAML designer.

Documentation for each control includes a "How to" topic that describes how to add the control in XAML, code, or using a design tool. For example, to add a Button control, see How to add a button.

Here, we use Visual Studio as our design tool, but you can do the same tasks and more in Blend for Visual Studio. For more info , see Creating a UI by using XAML Designer.

In Visual Studio, when you add and manipulate controls in your app, you can use many of the program's features, including the Toolbox, XAML designer, XAML editor, and the Properties window.

The Visual Studio Toolbox displays many of the controls that you can use in your app. To add a control to your app, double-click it in the Toolbox. For example, when you double-click the TextBox control, this XAML is added to the XAML view.

 <TextBox HorizontalAlignment="Left" Text="TextBox" VerticalAlignment="Top"/>

You can also drag the control from the Toolbox to the XAML designer.

Setting the name of a control

To work with a control in code, you set its x:Name attribute and reference it by name in your code. You can set the name in the Visual Studio Properties window or in XAML. Here's how to change the name of the currently selected control by using the Name text box at the top of the Properties window.

To name a control

  1. Select the element to name.
  2. In the Properties panel, type a name into the Name text box.
  3. Press Enter to commit the name.

Here's how you can change the name of a control in the XAML editor by changing the x:Name attribute.

<Button x:Name="Button1" Content="Button"/>

Setting control properties

You use properties to specify the appearance, content, and other attributes of controls. When you add a control using a design tool, some properties that control size, position, and content might be set for you by Visual Studio. You can change some properties, such as Width, Height or Margin, by selecting and manipulating the control in the Design view. This illustration shows some of the resizing tools available in Design view.

You might want to let the control be sized and positioned automatically. In this case, you can reset the size and position properties that Visual Studio set for you.

To reset a property

  1. In the Properties panel, click the property marker next to the property value. The property menu opens.

  2. In the property menu, click Reset.

You can set control properties in the Properties window, in XAML, or in code. For example, to change the foreground color for a Button, you set the control's Foreground property. This illustration shows how to set the Foreground property by using the color picker in the Properties window.

Here's how to set the Foreground property in the XAML editor. Notice the Visual Studio IntelliSense window that opens to help you with the syntax.

Here's the resulting XAML after you set the Foreground property.

<Button x:Name="Button1" Content="Button" 
    HorizontalAlignment="Left" VerticalAlignment="Top"
    Foreground="Beige"/>

Here's how to set the Foreground property in code.

Button1.Foreground = new SolidColorBrush(Windows.UI.Colors.Beige);

Button1.Foreground = new SolidColorBrush(Windows.UI.Colors.Beige)

Button1->Foreground = ref new Windows::UI::Xaml::Media::SolidColorBrush(Windows::UI::Colors::Beige);

Creating an event handler

Each control has events that enable you to respond to actions from your user or other changes in your app. For example, a Button control has a Click event that is raised when a user clicks the Button. You create a method, called an event handler, to handle the event. You can associate a control's event with an event handler method in the Properties window, in XAML, or in code. For more info about events, see Events and routed events overview.

To create an event handler, select the control and then click the Events tab at the top of the Properties window. The Properties window lists all of the events available for that control. Here are some of the events for a Button.

To create an event handler with the default name, double-click the text box next to the event name in the Properties window. To create an event handler with a custom name, type the name of your choice into the text box and press enter. The event handler is created and the code-behind file is opened in the code editor. The event handler method has 2 parameters. The first is sender, which is a reference to the object where the handler is attached. The sender parameter is an Object type. You typically cast sender to a more precise type if you expect to check or change state on the sender object itself. Based on your own app design, you expect a type that is safe to cast sender to, based on where the handler is attached. The second value is event data, which generally appears in signatures as the e parameter.

Here's code that handles the Click event of a Button named Button1. When you click the button, the Foreground property of the Button you clicked is set to blue.

private void Button_Click(object sender, RoutedEventArgs e)
{
    Button b = (Button)sender;
    b.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
}

Private Sub Button_Click(sender As Object, e As RoutedEventArgs)
    Dim b As Button = sender
    b.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue)
End Sub

//MainPage.xaml.h
void Button_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e);

//MainPage.xaml.cpp
void MainPage::Button_Click(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
    Button^ b = safe_cast<Button^>(sender);
    b->Foreground = ref new SolidColorBrush(Windows::UI::Colors::Blue);
}

You can also associate an event handler in XAML. In the XAML editor, you type in the event name that you want to handle. Visual Studio shows an IntelliSense window when you begin typing. After you specify the event, you can double-click <New Event Handler> in the IntelliSense window to create a new event handler with the default name, or select an existing event handler from the list. Here's the IntelliSense window that appears to help you create a new event handler.

This example shows how to associate a Click event with an event handler named Button_Click in XAML.

<Button Name="Button1" Content="Button" Click="Button_Click"/>

You can also associate an event with its event handler in the code-behind. Here's how to associate an event handler in code.

Button1.Click += new RoutedEventHandler(Button_Click);

AddHandler Button1.Click, AddressOf Me.Button_Click

Button1->Click += ref new RoutedEventHandler(this, &MainPage::Button_Click);

New controls

If you use other XAML platforms, you might be interested in these controls that are new for Windows 8.

You can learn more about these and other controls in the Controls list.

What's Next

You now know the basics of adding a control to your app, setting control properties, and creating event handlers. Next, you'll learn more about which controls are available: Controls list orControls by function. You can also see many of the Windows UI controls by downloading the Basic controls sample.

Events and routed events overview

Controls list

Creating a UI by using XAML Designer

Roadmap for creating apps using C#, C++, or VB