Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b90a140

Browse files
adegeogewarren
adegeo
and
gewarren
authored
Port and improve WPF controls overview (#2011)
* port and rework WPF controls overview * Change see also * Build errors * tweaks * tweaks * Add VB code * Add reference to the vb code * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Genevieve Warren <[email protected]>
1 parent ce615fd commit b90a140

36 files changed

+1547
-0
lines changed

‎dotnet-desktop-guide/net/wpf/controls/index.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Controls
3+
description: This article introduces WPF controls, detailing their creation, styling, templating, events, and rich content support via XAML or code.
4+
ms.date: 02/19/2025
5+
ms.topic: overview
6+
dev_langs:
7+
- "csharp"
8+
- "vb"
9+
helpviewer_keywords:
10+
- "controls [WPF], about WPF controls"
11+
12+
#customer intent: As a developer, I want to understand WPF controls so that I know their capabilities, especially in ways they compare to other desktop technologies.
13+
---
14+
# What are controls? (WPF .NET)
15+
16+
Windows Presentation Foundation (WPF) ships with many of the common UI components that are used in almost every Windows app, such as <xref:System.Windows.Controls.Button>, <xref:System.Windows.Controls.Label>, <xref:System.Windows.Controls.TextBox>, <xref:System.Windows.Controls.Menu>, and <xref:System.Windows.Controls.ListBox>. Historically, these objects are referred to as controls. The term "control" is used loosely to mean any class that represents a visible object in an app. It's important to note that a class doesn't need to inherit from the <xref:System.Windows.Controls.Control> class to have a visible presence. Classes that inherit from the `Control` class contain a <xref:System.Windows.Controls.ControlTemplate>, which allows the consumer of a control to radically change the control's appearance without having to create a new subclass. This article discusses how controls (both those that do inherit from the `Control` class and those that don't) are commonly used in WPF.
17+
18+
## Create an instance of a control
19+
20+
You can add a control to an app by using either Extensible Application Markup Language (XAML) or code. For example, consider the following image of a WPF window that asks a user for their name and address:
21+
22+
:::image type="content" source="./media/index/xaml-example.png" alt-text="A screenshot of a WPF app with two text boxes labeled name and address. Two buttons are visible. One button is named 'Reset' and the other 'Submit.'":::
23+
24+
This window has six controls: two labels, two text boxes, and two buttons. XAML is used to create these controls, as demonstrated in the following snippet:
25+
26+
:::code language="xaml" source="./snippets/index/csharp/ExampleApp.xaml":::
27+
28+
All controls can be created similarly in XAML. The same window can be created in code:
29+
30+
:::code language="csharp" source="./snippets/index/csharp/MainWindow.xaml.cs" id="ExampleAppCode":::
31+
:::code language="vb" source="./snippets/index/vb/MainWindow.xaml.vb" id="ExampleAppCode":::
32+
33+
## Subscribe to events
34+
35+
You can subscribe to a control's event by using either XAML or code, but you can only handle an event in code.
36+
37+
In XAML, the event is set as an attribute on the element. You can't use the `<Element.Event>handler<Element.Event>` notation for events. The following snippet shows how to subscribe to the `Click` event of a <xref:System.Windows.Controls.Button>:
38+
39+
:::code language="xaml" source="./snippets/index/csharp/ButtonClickEventExample.xaml" id="Event":::
40+
41+
And here's how to do the same in code:
42+
43+
:::code language="csharp" source="./snippets/index/csharp/MainWindow.xaml.cs" id="Event":::
44+
:::code language="vb" source="./snippets/index/vb/MainWindow.xaml.vb" id="Event":::
45+
46+
The following snippet handles the `Click` event of a <xref:System.Windows.Controls.Button>:
47+
48+
:::code language="csharp" source="./snippets/index/csharp/ButtonClickEventExample.xaml.cs" id="ClickHandler":::
49+
:::code language="vb" source="./snippets/index/vb/ButtonClickEventExample.xaml.vb" id="ClickHandler":::
50+
51+
## Change the appearance of a control
52+
53+
It's common to change the appearance of a control to fit the look and feel of your app. You can change the appearance of a control by doing one of the following, depending on what you want to accomplish:
54+
55+
- Change the value of a property of the control.
56+
- Create a <xref:System.Windows.Style> for the control.
57+
- Create a new <xref:System.Windows.Controls.ControlTemplate> for the control.
58+
59+
### Change a control's property
60+
61+
Many controls have properties that allow you to change how the control appears, such as a button's background. You can set the value properties in both XAML and code. The following example sets the <xref:System.Windows.Controls.Control.Background%2A>, <xref:System.Windows.Controls.Control.FontSize%2A>, and <xref:System.Windows.Controls.Control.FontWeight%2A> properties on a `Button` in XAML:
62+
63+
:::code language="xaml" source="./snippets/index/csharp/ButtonPropertyWindow.xaml" id="Properties":::
64+
65+
And here's how to do the same in code:
66+
67+
:::code language="csharp" source="./snippets/index/csharp/MainWindow.xaml.cs" id="Properties":::
68+
:::code language="vb" source="./snippets/index/vb/MainWindow.xaml.vb" id="Properties":::
69+
70+
The example window now looks like the following image:
71+
72+
:::image type="content" source="./media/index/xaml-example-property.png" alt-text="A screenshot of a WPF app with two text boxes labeled name and address. Two buttons are visible. One button is named 'Reset' and the other 'Submit.' The 'Submit' button has a gradient background that transitions from a blue to a lighter blue.":::
73+
74+
### Create a style for a control
75+
76+
WPF gives you extensive ability to specify the appearance of controls by creating a <xref:System.Windows.Style>, instead of setting properties on each control. `Style` definitions are typically defined in XAML in a <xref:System.Windows.ResourceDictionary>, such as the <xref:System.Windows.FrameworkElement.Resources%2A> property of a control or Window. Resources are applied to the scope in which they're declared. For more information, see [Overview of XAML resources](../systems/xaml-resources-overview.md).
77+
78+
The following example applies a `Style` to every <xref:System.Windows.Controls.Button> contained in the same `Grid` that defines the style:
79+
80+
:::code language="xaml" source="./snippets/index/csharp/ButtonStyleWindow.xaml" id="Style":::
81+
82+
And here's how to do the same in code:
83+
84+
:::code language="csharp" source="./snippets/index/csharp/MainWindow.xaml.cs" id="Style":::
85+
:::code language="vb" source="./snippets/index/vb/MainWindow.xaml.vb" id="Style":::
86+
87+
The following image shows the style applied to the grid of the window, which changes the appearance of the two buttons:
88+
89+
:::image type="content" source="./media/index/xaml-example-style.png" alt-text="A screenshot of a WPF app with two text boxes labeled name and address. Two buttons are visible. One button is named 'Reset' and the other 'Submit.' Both buttons feature a gradient background that transitions from a blue to a lighter blue.":::
90+
91+
Instead of applying the style to all controls of a specific type, they can also be assigned to specific controls by adding a key to the style in the resource dictionary, and referencing that key in the `Style` property of the control. For more information about styles, see [Styling and Templating](styles-templates-overview.md).
92+
93+
### Create a ControlTemplate
94+
95+
A `Style` allows you to set properties on multiple controls at a time, but sometimes you might want to customize the appearance of a control beyond what you can do with a <xref:System.Windows.Style>. Classes that inherit from the <xref:System.Windows.Controls.Control> class have a <xref:System.Windows.Controls.ControlTemplate>, which defines the structure and appearance of a control.
96+
97+
Consider the <xref:System.Windows.Controls.Button> control, a common control used by almost every app. The primary behavior of a button is to enable an app to take some action when the user selects the button. By default, the button in WPF appears as a raised rectangle. While developing an app, you might want to take advantage of the behavior of a button&mdash;that is, how the user interacts with the button, which raises a `Click` event&mdash;but you might change the button's appearance beyond what you can do by changing the button's properties. In this case, you can create a new <xref:System.Windows.Controls.ControlTemplate>.
98+
99+
The following example creates a <xref:System.Windows.Controls.ControlTemplate> for a <xref:System.Windows.Controls.Button>. The `ControlTemplate` creates a visual for the `Button` that presents a border with rounded corners and a gradient background.
100+
101+
:::code language="xaml" source="./snippets/index/csharp/ButtonTemplateWindow.xaml" id="Template":::
102+
103+
> [!NOTE]
104+
> The <xref:System.Windows.Controls.Control.Background%2A> property of the <xref:System.Windows.Controls.Button> must be set to a <xref:System.Windows.Media.SolidColorBrush> for the example to work properly.
105+
106+
And here's how to do the same in code. The following code creates a XAML string and parses it to generate a template that can be applied, which is the supported way to generate a template at run-time.
107+
108+
:::code language="csharp" source="./snippets/index/csharp/MainWindow.xaml.cs" id="Template":::
109+
:::code language="vb" source="./snippets/index/vb/MainWindow.xaml.vb" id="Template":::
110+
111+
The following image shows what the template looks like when applied:
112+
113+
:::image type="content" source="./media/index/xaml-example-template.png" alt-text="A screenshot of a WPF app with two text boxes labeled name and address. Two buttons are visible. One button is named 'Reset' and the other 'Submit.' The 'Submit' button has rounded corners and a peach color applied to it.":::
114+
115+
In the previous example, the `ControlTemplate` is applied to a single button. However, a `ControlTemplate` can be assigned to a `Style` and applied to all buttons, like what was demonstrated in the [Create a style for a control](#create-a-style-for-a-control) section.
116+
117+
For more information about how to take advantage of the unique features a template provides, see [Styling and Templating](styles-templates-overview.md).
118+
119+
## Rich content in controls
120+
121+
Most classes that inherit from the <xref:System.Windows.Controls.Control> class have the capacity to contain rich content. For example, a <xref:System.Windows.Controls.Label> can contain any object, such as a string, an <xref:System.Windows.Controls.Image>, or a <xref:System.Windows.Controls.Panel>. The following classes provide support for rich content and act as base classes for most of the controls in WPF:
122+
123+
- <xref:System.Windows.Controls.ContentControl>&mdash;Some examples of classes that inherit from this class are <xref:System.Windows.Controls.Label>, <xref:System.Windows.Controls.Button>, and <xref:System.Windows.Controls.ToolTip>.
124+
125+
- <xref:System.Windows.Controls.ItemsControl>&mdash;Some examples of classes that inherit from this class are <xref:System.Windows.Controls.ListBox>, <xref:System.Windows.Controls.Menu>, and <xref:System.Windows.Controls.Primitives.StatusBar>.
126+
127+
- <xref:System.Windows.Controls.HeaderedContentControl>&mdash;Some examples of classes that inherit from this class are <xref:System.Windows.Controls.TabItem>, <xref:System.Windows.Controls.GroupBox>, and <xref:System.Windows.Controls.Expander>.
128+
129+
- <xref:System.Windows.Controls.HeaderedItemsControl>&mdash;Some examples of classes that inherit from this class are <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Controls.TreeViewItem>, and <xref:System.Windows.Controls.ToolBar>.
130+
131+
<!--For more information about these base classes, see [WPF Content Model](wpf-content-model.md).-->
132+
133+
## Related content
134+
135+
- [Styling and Templating](styles-templates-overview.md)
136+
- [Data binding overview](../data/index.md)

‎dotnet-desktop-guide/net/wpf/controls/media/index/xaml-example-property.png‎

6.88 KB
Loading

‎dotnet-desktop-guide/net/wpf/controls/media/index/xaml-example-style.png‎

7.7 KB
Loading

‎dotnet-desktop-guide/net/wpf/controls/media/index/xaml-example-template.png‎

6.17 KB
Loading

‎dotnet-desktop-guide/net/wpf/controls/media/index/xaml-example.png‎

5.27 KB
Loading

‎dotnet-desktop-guide/net/wpf/controls/snippets/index/csharp/App.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// // Copyright (c) Microsoft. All rights reserved.
2+
// // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3+
4+
using System.Windows;
5+
6+
namespace Examples
7+
{
8+
/// <summary>
9+
/// Interaction logic for App.xaml
10+
/// </summary>
11+
public partial class App : Application
12+
{
13+
}
14+
}

‎dotnet-desktop-guide/net/wpf/controls/snippets/index/csharp/App.xaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Application x:Class="Examples.App"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
xmlns:local="clr-namespace:Examples"
5+
StartupUri="MainWindow.xaml">
6+
<Application.Resources>
7+
8+
</Application.Resources>
9+
</Application>

‎dotnet-desktop-guide/net/wpf/controls/snippets/index/csharp/ButtonClickEventExample.xaml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<Window x:Class="Examples.ButtonClickEventExample"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
Title="Input Record" Height="Auto" Width="300" SizeToContent="Height">
5+
<Grid Margin="5">
6+
<Grid.RowDefinitions>
7+
<RowDefinition Height="30"/>
8+
<RowDefinition Height="30"/>
9+
<RowDefinition Height="30"/>
10+
</Grid.RowDefinitions>
11+
<Grid.ColumnDefinitions>
12+
<ColumnDefinition/>
13+
<ColumnDefinition/>
14+
</Grid.ColumnDefinitions>
15+
16+
<Label>Enter your name:</Label>
17+
<TextBox Grid.Row="0" Grid.Column="1" Name="FirstName" Margin="2" />
18+
19+
<Label Grid.Row="1">Enter your address:</Label>
20+
<TextBox Grid.Row="1" Grid.Column="1" Name="LastName" Margin="2" />
21+
22+
<Button Grid.Row="2" Grid.Column="0" Name="Reset" Margin="2">Reset</Button>
23+
<!-- <SnippetEvent> -->
24+
<Button Click="Submit_Click" Grid.Row="2" Grid.Column="1" Name="Submit" Margin="2">Submit</Button>
25+
<!-- </SnippetEvent> -->
26+
</Grid>
27+
</Window>

‎dotnet-desktop-guide/net/wpf/controls/snippets/index/csharp/ButtonClickEventExample.xaml.cs‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Linq;
4+
using System.Text;
5+
using System.Threading.Tasks;
6+
using System.Windows;
7+
using System.Windows.Controls;
8+
using System.Windows.Data;
9+
using System.Windows.Documents;
10+
using System.Windows.Input;
11+
using System.Windows.Media;
12+
using System.Windows.Media.Imaging;
13+
using System.Windows.Shapes;
14+
15+
namespace Examples
16+
{
17+
/// <summary>
18+
/// Interaction logic for ButtonClickEventExample.xaml
19+
/// </summary>
20+
public partial class ButtonClickEventExample : Window
21+
{
22+
public ButtonClickEventExample()
23+
{
24+
InitializeComponent();
25+
}
26+
27+
// <ClickHandler>
28+
private void Submit_Click(object sender, RoutedEventArgs e)
29+
{
30+
MessageBox.Show("Someone clicked the submit button.");
31+
}
32+
// </ClickHandler>
33+
34+
}
35+
}

‎dotnet-desktop-guide/net/wpf/controls/snippets/index/csharp/ButtonPropertyWindow.xaml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<Window x:Class="Examples.ButtonPropertyWindow"
2+
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3+
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4+
Title="Input Record" Height="Auto" Width="300" SizeToContent="Height">
5+
<Grid Margin="5">
6+
<Grid.RowDefinitions>
7+
<RowDefinition Height="30"/>
8+
<RowDefinition Height="30"/>
9+
<RowDefinition Height="30"/>
10+
</Grid.RowDefinitions>
11+
<Grid.ColumnDefinitions>
12+
<ColumnDefinition/>
13+
<ColumnDefinition/>
14+
</Grid.ColumnDefinitions>
15+
16+
<Label>Enter your name:</Label>
17+
<TextBox Grid.Row="0" Grid.Column="1" Name="FirstName" Margin="2" />
18+
19+
<Label Grid.Row="1">Enter your address:</Label>
20+
<TextBox Grid.Row="1" Grid.Column="1" Name="LastName" Margin="2" />
21+
22+
<Button Grid.Row="2" Grid.Column="0" Name="Reset" Margin="2">Reset</Button>
23+
<!--<SnippetProperties>-->
24+
<Button Grid.Row="2" Grid.Column="1" Name="Submit" Margin="2" Content="Submit">
25+
<Button.FontSize>18</Button.FontSize>
26+
<Button.FontWeight>Bold</Button.FontWeight>
27+
<Button.Background>
28+
<LinearGradientBrush>
29+
<GradientStop Color="#0073E6" Offset="0.0" />
30+
<GradientStop Color="#81D4FA" Offset="0.9" />
31+
</LinearGradientBrush>
32+
</Button.Background>
33+
</Button>
34+
<!--</SnippetProperties>-->
35+
</Grid>
36+
</Window>

0 commit comments

Comments
 (0)