Replace various WPF include files with content (#1335)

* net-current-v30plus-md.md

* net-current-v40plus-md.md

* tla2sharptla-ui-md.md

* tla2sharptla-uiautomation-md.md

* tla2sharptla-winclient-md.md

* tla2sharptla-xaml-md.md

* tlasharptla-ui-md.md

* tlasharptla-uiautomation-md.md

* tlasharptla-winclient-md.md

* tlasharptla-xaml-md.md

* fix warnings
This commit is contained in:
Andy (Steve) De George
2022-03-16 12:14:11 -04:00
committed by GitHub
parent dd0052ecec
commit be103da07e
353 changed files with 1339 additions and 1349 deletions
@@ -8,7 +8,7 @@ helpviewer_keywords:
ms.assetid: e29d7516-d5e6-4500-bd4f-775e6f830984
---
# Adorners How-to Topics
The following examples demonstrate how to accomplish common tasks using the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] adorner framework.
The following examples demonstrate how to accomplish common tasks using the Windows Presentation Foundation (WPF) adorner framework.
## In This Section
[Implement an Adorner](how-to-implement-an-adorner.md)
@@ -26,7 +26,7 @@ Common applications for adorners include:
- Overlay visual decorations on a <xref:System.Windows.UIElement>.
- Visually mask or override part or all of a <xref:System.Windows.UIElement>.
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a basic framework for adorning visual elements. The following table lists the primary types used when adorning objects, and their purpose. Several usage examples follow:
Windows Presentation Foundation (WPF) provides a basic framework for adorning visual elements. The following table lists the primary types used when adorning objects, and their purpose. Several usage examples follow:
| Class | Description |
|------|-------------|
@@ -36,7 +36,7 @@ Common applications for adorners include:
## Implementing a Custom Adorner
The adorners framework provided by [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is intended primarily to support the creation of custom adorners. A custom adorner is created by implementing a class that inherits from the abstract <xref:System.Windows.Documents.Adorner> class.
The adorners framework provided by Windows Presentation Foundation (WPF) is intended primarily to support the creation of custom adorners. A custom adorner is created by implementing a class that inherits from the abstract <xref:System.Windows.Documents.Adorner> class.
> [!NOTE]
> The parent of an <xref:System.Windows.Documents.Adorner> is the <xref:System.Windows.Documents.AdornerLayer> that renders the <xref:System.Windows.Documents.Adorner>, not the element being adorned.
@@ -77,7 +77,7 @@ To bind an adorner to a particular <xref:System.Windows.UIElement>, follow these
[!code-vb[Adorners_SimpleCircleAdorner#_AdornSingleElement](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Adorners_SimpleCircleAdorner/VisualBasic/Window1.xaml.vb#_adornsingleelement)]
> [!NOTE]
> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported.
> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported.
## Adorning the Children of a Panel
@@ -8,7 +8,7 @@ helpviewer_keywords:
ms.assetid: 5d5f656b-8e05-4839-9d53-b0324d902aa9
---
# Adorners
This section provides information about Adorners and the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] Adorner framework.
This section provides information about Adorners and the Windows Presentation Foundation (WPF) Adorner framework.
## In This Section
[Adorners Overview](adorners-overview.md)
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: a9d8f5a5-c98c-463e-808a-5a4e63173098
---
# Button
A <xref:System.Windows.Controls.Button> control reacts to user input from a mouse, keyboard, stylus, or other input device and raises a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event. A <xref:System.Windows.Controls.Button> is a basic [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] component that can contain simple content, such as text, and can also contain complex content, such as images and <xref:System.Windows.Controls.Panel> controls.
A <xref:System.Windows.Controls.Button> control reacts to user input from a mouse, keyboard, stylus, or other input device and raises a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event. A <xref:System.Windows.Controls.Button> is a basic user interface (UI) component that can contain simple content, such as text, and can also contain complex content, such as images and <xref:System.Windows.Controls.Panel> controls.
![Button states](./media/ss-ctl-buttons.png "SS_CTL_buttons")
@@ -15,7 +15,7 @@ ms.assetid: f1213205-1ad7-4cd2-b115-460173cc5aa3
This example shows how to programmatically change the current selection in a <xref:System.Windows.Controls.RichTextBox>. This selection is the same as if the user had selected the content by using the user interface.
## Code example for a RichTextBox control
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a named <xref:System.Windows.Controls.RichTextBox> control with simple content.
The following Extensible Application Markup Language (XAML) code describes a named <xref:System.Windows.Controls.RichTextBox> control with simple content.
[!code-xaml[RichTextBoxMiscSnippets_snip#ChangeSelectionProgrammaticalyExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/RichTextBoxMiscSnippets_snip/CSharp/ChangeSelectionProgrammaticaly.xaml#changeselectionprogrammaticalyexamplewholepage)]
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: ee701cc2-968b-4683-8f81-3fafd8542700
---
# CheckBox
You can use a <xref:System.Windows.Controls.CheckBox> in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] of your application to represent options that a user can select or clear. You can use a single check box or you can group two or more check boxes.
You can use a <xref:System.Windows.Controls.CheckBox> in the user interface (UI) of your application to represent options that a user can select or clear. You can use a single check box or you can group two or more check boxes.
The following graphic shows the different states of a <xref:System.Windows.Controls.CheckBox>.
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 16909c42-799a-4561-91e0-7d69dcfeea91
---
# ContextMenu Overview
The <xref:System.Windows.Controls.ContextMenu> class represents the element that exposes functionality by using a context-specific <xref:System.Windows.Controls.Menu>. Typically, a user exposes the <xref:System.Windows.Controls.ContextMenu> in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] by right-clicking the mouse button. This topic introduces the <xref:System.Windows.Controls.ContextMenu> element and provides examples of how to use it in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code.
The <xref:System.Windows.Controls.ContextMenu> class represents the element that exposes functionality by using a context-specific <xref:System.Windows.Controls.Menu>. Typically, a user exposes the <xref:System.Windows.Controls.ContextMenu> in the user interface (UI) by right-clicking the mouse button. This topic introduces the <xref:System.Windows.Controls.ContextMenu> element and provides examples of how to use it in Extensible Application Markup Language (XAML) and code.
<a name="contextmenu_control"></a>
## ContextMenu Control
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 2f40b2bb-b702-4706-9fc4-10bcfd7cc35d
---
# ContextMenu
The <xref:System.Windows.Controls.ContextMenu> allows a control to display a <xref:System.Windows.Controls.Menu> that is specific to the context of the control. Typically, the <xref:System.Windows.Controls.ContextMenu> is exposed in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] through the right mouse button or through the keyboards menu button.
The <xref:System.Windows.Controls.ContextMenu> allows a control to display a <xref:System.Windows.Controls.Menu> that is specific to the context of the control. Typically, the <xref:System.Windows.Controls.ContextMenu> is exposed in the user interface (UI) through the right mouse button or through the keyboards menu button.
The following figure illustrates a <xref:System.Windows.Controls.ContextMenu> in two different states: the default state and the open state. In the default state, the control is collapsed. When the right mouse button is pressed over the parent of the menu, the control expands and displays the menu items.
@@ -13,21 +13,21 @@ ms.assetid: 3d864748-cff0-4e63-9b23-d8e5a635b28f
---
# Control authoring overview
The extensibility of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control model greatly reduces the need to create a new control. However, in certain cases you may still need to create a custom control. This topic discusses the features that minimize your need to create a custom control and the different control authoring models in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. This topic also demonstrates how to create a new control.
The extensibility of the Windows Presentation Foundation (WPF) control model greatly reduces the need to create a new control. However, in certain cases you may still need to create a custom control. This topic discusses the features that minimize your need to create a custom control and the different control authoring models in Windows Presentation Foundation (WPF). This topic also demonstrates how to create a new control.
<a name="when_to_write_a_new_control"></a>
## Alternatives to Writing a New Control
Historically, if you wanted to get a customized experience from an existing control, you were limited to changing the standard properties of the control, such as background color, border width, and font size. If you wished to extend the appearance or behavior of a control beyond these predefined parameters, you would need to create a new control, usually by inheriting from an existing control and overriding the method responsible for drawing the control. Although that is still an option, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables to you customize existing controls by using its rich content model, styles, templates, and triggers. The following list gives examples of how these features can be used to create custom and consistent experiences without having to create a new control.
Historically, if you wanted to get a customized experience from an existing control, you were limited to changing the standard properties of the control, such as background color, border width, and font size. If you wished to extend the appearance or behavior of a control beyond these predefined parameters, you would need to create a new control, usually by inheriting from an existing control and overriding the method responsible for drawing the control. Although that is still an option, WPF enables to you customize existing controls by using its rich content model, styles, templates, and triggers. The following list gives examples of how these features can be used to create custom and consistent experiences without having to create a new control.
- **Rich Content.** Many of the standard [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls support rich content. For example, the content property of a <xref:System.Windows.Controls.Button> is of type <xref:System.Object>, so theoretically anything can be displayed on a <xref:System.Windows.Controls.Button>. To have a button display an image and text, you can add an image and a <xref:System.Windows.Controls.TextBlock> to a <xref:System.Windows.Controls.StackPanel> and assign the <xref:System.Windows.Controls.StackPanel> to the <xref:System.Windows.Controls.ContentControl.Content%2A> property. Because the controls can display [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] visual elements and arbitrary data, there is less need to create a new control or to modify an existing control to support a complex visualization. For more information about the content model for <xref:System.Windows.Controls.Button> and other content models in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [WPF Content Model](wpf-content-model.md).
- **Rich Content.** Many of the standard WPF controls support rich content. For example, the content property of a <xref:System.Windows.Controls.Button> is of type <xref:System.Object>, so theoretically anything can be displayed on a <xref:System.Windows.Controls.Button>. To have a button display an image and text, you can add an image and a <xref:System.Windows.Controls.TextBlock> to a <xref:System.Windows.Controls.StackPanel> and assign the <xref:System.Windows.Controls.StackPanel> to the <xref:System.Windows.Controls.ContentControl.Content%2A> property. Because the controls can display WPF visual elements and arbitrary data, there is less need to create a new control or to modify an existing control to support a complex visualization. For more information about the content model for <xref:System.Windows.Controls.Button> and other content models in WPF, see [WPF Content Model](wpf-content-model.md).
- **Styles.** A <xref:System.Windows.Style> is a collection of values that represent properties for a control. By using styles, you can create a reusable representation of a desired control appearance and behavior without writing a new control. For example, assume that you want all of your <xref:System.Windows.Controls.TextBlock> controls to have red, Arial font with a font size of 14. You can create a style as a resource and set the appropriate properties accordingly. Then every <xref:System.Windows.Controls.TextBlock> that you add to your application will have the same appearance.
- **Data Templates.** A <xref:System.Windows.DataTemplate> enables you to customize how data is displayed on a control. For example, a <xref:System.Windows.DataTemplate> can be used to specify how data is displayed in a <xref:System.Windows.Controls.ListBox>. For an example of this, see [Data Templating Overview](../data/data-templating-overview.md). In addition to customizing the appearance of data, a <xref:System.Windows.DataTemplate> can include UI elements, which gives you a lot of flexibility in custom UIs. For example, by using a <xref:System.Windows.DataTemplate>, you can create a <xref:System.Windows.Controls.ComboBox> in which each item contains a check box.
- **Control Templates.** Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] use a <xref:System.Windows.Controls.ControlTemplate> to define the control's structure and appearance, which separates the appearance of a control from the functionality of the control. You can drastically change the appearance of a control by redefining its <xref:System.Windows.Controls.ControlTemplate>. For example, suppose you want a control that looks like a stoplight. This control has a simple user interface and functionality. The control is three circles, only one of which can be lit up at a time. After some reflection, you might realize that a <xref:System.Windows.Controls.RadioButton> offers the functionality of only one being selected at a time, but the default appearance of the <xref:System.Windows.Controls.RadioButton> looks nothing like the lights on a stoplight. Because the <xref:System.Windows.Controls.RadioButton> uses a control template to define its appearance, it is easy to redefine the <xref:System.Windows.Controls.ControlTemplate> to fit the requirements of the control, and use radio buttons to make your stoplight.
- **Control Templates.** Many controls in WPF use a <xref:System.Windows.Controls.ControlTemplate> to define the control's structure and appearance, which separates the appearance of a control from the functionality of the control. You can drastically change the appearance of a control by redefining its <xref:System.Windows.Controls.ControlTemplate>. For example, suppose you want a control that looks like a stoplight. This control has a simple user interface and functionality. The control is three circles, only one of which can be lit up at a time. After some reflection, you might realize that a <xref:System.Windows.Controls.RadioButton> offers the functionality of only one being selected at a time, but the default appearance of the <xref:System.Windows.Controls.RadioButton> looks nothing like the lights on a stoplight. Because the <xref:System.Windows.Controls.RadioButton> uses a control template to define its appearance, it is easy to redefine the <xref:System.Windows.Controls.ControlTemplate> to fit the requirements of the control, and use radio buttons to make your stoplight.
> [!NOTE]
> Although a <xref:System.Windows.Controls.RadioButton> can use a <xref:System.Windows.DataTemplate>, a <xref:System.Windows.DataTemplate> is not sufficient in this example. The <xref:System.Windows.DataTemplate> defines the appearance of the content of a control. In the case of a <xref:System.Windows.Controls.RadioButton>, the content is whatever appears to the right of the circle that indicates whether the <xref:System.Windows.Controls.RadioButton> is selected. In the example of the stoplight, the radio button needs just be a circle that can "light up." Because the appearance requirement for the stoplight is so different than the default appearance of the <xref:System.Windows.Controls.RadioButton>, it is necessary to redefine the <xref:System.Windows.Controls.ControlTemplate>. In general a <xref:System.Windows.DataTemplate> is used for defining the content (or data) of a control, and a <xref:System.Windows.Controls.ControlTemplate> is used for defining how a control is structured.
@@ -42,11 +42,11 @@ In general, if your control mirrors the functionality of an existing control, bu
## Models for Control Authoring
The rich content model, styles, templates, and triggers minimize the need for you to create a new control. However, if you do need to create a new control, it is important to understand the different control authoring models in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides three general models for creating a control, each of which provides a different set of features and level of flexibility. The base classes for the three models are <xref:System.Windows.Controls.UserControl>, <xref:System.Windows.Controls.Control>, and <xref:System.Windows.FrameworkElement>.
The rich content model, styles, templates, and triggers minimize the need for you to create a new control. However, if you do need to create a new control, it is important to understand the different control authoring models in WPF. WPF provides three general models for creating a control, each of which provides a different set of features and level of flexibility. The base classes for the three models are <xref:System.Windows.Controls.UserControl>, <xref:System.Windows.Controls.Control>, and <xref:System.Windows.FrameworkElement>.
### Deriving from UserControl
The simplest way to create a control in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to derive from <xref:System.Windows.Controls.UserControl>. When you build a control that inherits from <xref:System.Windows.Controls.UserControl>, you add existing components to the <xref:System.Windows.Controls.UserControl>, name the components, and reference event handlers in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. You can then reference the named elements and define the event handlers in code. This development model is very similar to the model used for application development in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
The simplest way to create a control in WPF is to derive from <xref:System.Windows.Controls.UserControl>. When you build a control that inherits from <xref:System.Windows.Controls.UserControl>, you add existing components to the <xref:System.Windows.Controls.UserControl>, name the components, and reference event handlers in WPF.
If built correctly, a <xref:System.Windows.Controls.UserControl> can take advantage of the benefits of rich content, styles, and triggers. However, if your control inherits from <xref:System.Windows.Controls.UserControl>, people who use your control will not be able to use a <xref:System.Windows.DataTemplate> or <xref:System.Windows.Controls.ControlTemplate> to customize its appearance. It is necessary to derive from the <xref:System.Windows.Controls.Control> class or one of its derived classes (other than <xref:System.Windows.Controls.UserControl>) to create a custom control that supports templates.
@@ -62,7 +62,7 @@ Consider deriving from <xref:System.Windows.Controls.UserControl> if all of the
### Deriving from Control
Deriving from the <xref:System.Windows.Controls.Control> class is the model used by most of the existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls. When you create a control that inherits from the <xref:System.Windows.Controls.Control> class, you define its appearance by using templates. By doing so, you separate the operational logic from the visual representation. You can also ensure the decoupling of the UI and logic by using commands and bindings instead of events and avoiding referencing elements in the <xref:System.Windows.Controls.ControlTemplate> whenever possible. If the UI and logic of your control are properly decoupled, a user of your control can redefine the control's <xref:System.Windows.Controls.ControlTemplate> to customize its appearance. Although building a custom <xref:System.Windows.Controls.Control> is not as simple as building a <xref:System.Windows.Controls.UserControl>, a custom <xref:System.Windows.Controls.Control> provides the most flexibility.
Deriving from the <xref:System.Windows.Controls.Control> class is the model used by most of the existing WPF controls. When you create a control that inherits from the <xref:System.Windows.Controls.Control> class, you define its appearance by using templates. By doing so, you separate the operational logic from the visual representation. You can also ensure the decoupling of the UI and logic by using commands and bindings instead of events and avoiding referencing elements in the <xref:System.Windows.Controls.ControlTemplate> whenever possible. If the UI and logic of your control are properly decoupled, a user of your control can redefine the control's <xref:System.Windows.Controls.ControlTemplate> to customize its appearance. Although building a custom <xref:System.Windows.Controls.Control> is not as simple as building a <xref:System.Windows.Controls.UserControl>, a custom <xref:System.Windows.Controls.Control> provides the most flexibility.
#### Benefits of Deriving from Control
@@ -76,7 +76,7 @@ Consider deriving from <xref:System.Windows.Controls.Control> instead of using t
Controls that derive from <xref:System.Windows.Controls.UserControl> or <xref:System.Windows.Controls.Control> rely upon composing existing elements. For many scenarios, this is an acceptable solution, because any object that inherits from <xref:System.Windows.FrameworkElement> can be in a <xref:System.Windows.Controls.ControlTemplate>. However, there are times when a control's appearance requires more than the functionality of simple element composition. For these scenarios, basing a component on <xref:System.Windows.FrameworkElement> is the right choice.
There are two standard methods for building <xref:System.Windows.FrameworkElement>-based components: direct rendering and custom element composition. Direct rendering involves overriding the <xref:System.Windows.UIElement.OnRender%2A> method of <xref:System.Windows.FrameworkElement> and providing <xref:System.Windows.Media.DrawingContext> operations that explicitly define the component visuals. This is the method used by <xref:System.Windows.Controls.Image> and <xref:System.Windows.Controls.Border>. Custom element composition involves using objects of type <xref:System.Windows.Media.Visual> to compose the appearance of your component. For an example, see [Using DrawingVisual Objects](../graphics-multimedia/using-drawingvisual-objects.md). <xref:System.Windows.Controls.Primitives.Track> is an example of a control in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] that uses custom element composition. It is also possible to mix direct rendering and custom element composition in the same control.
There are two standard methods for building <xref:System.Windows.FrameworkElement>-based components: direct rendering and custom element composition. Direct rendering involves overriding the <xref:System.Windows.UIElement.OnRender%2A> method of <xref:System.Windows.FrameworkElement> and providing <xref:System.Windows.Media.DrawingContext> operations that explicitly define the component visuals. This is the method used by <xref:System.Windows.Controls.Image> and <xref:System.Windows.Controls.Border>. Custom element composition involves using objects of type <xref:System.Windows.Media.Visual> to compose the appearance of your component. For an example, see [Using DrawingVisual Objects](../graphics-multimedia/using-drawingvisual-objects.md). <xref:System.Windows.Controls.Primitives.Track> is an example of a control in WPF that uses custom element composition. It is also possible to mix direct rendering and custom element composition in the same control.
#### Benefits of Deriving from FrameworkElement
@@ -92,7 +92,7 @@ Consider deriving from <xref:System.Windows.FrameworkElement> if any of the foll
## Control Authoring Basics
As discussed earlier, one of the most powerful features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is the ability to go beyond setting basic properties of a control to change its appearance and behavior, yet still not needing to create a custom control. The styling, data binding, and trigger features are made possible by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system and the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. The following sections describe some practices that you should follow, regardless of the model you use to create the custom control, so that users of your custom control can use these features just as they would for a control that is included with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
As discussed earlier, one of the most powerful features of WPF is the ability to go beyond setting basic properties of a control to change its appearance and behavior, yet still not needing to create a custom control. The styling, data binding, and trigger features are made possible by the WPF property system and the WPF event system. The following sections describe some practices that you should follow, regardless of the model you use to create the custom control, so that users of your custom control can use these features just as they would for a control that is included with WPF.
### Use Dependency Properties
@@ -120,7 +120,7 @@ If you want a property of your control to support any of this functionality, you
- The metadata for the property. The metadata contains the property's default value, a <xref:System.Windows.CoerceValueCallback> and a <xref:System.Windows.PropertyChangedCallback>.
- Define a CLR wrapper property named `Value`, which is the same name that is used to register the dependency property, by implementing the property's `get` and `set` accessors. Note that the `get` and `set` accessors only call <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> respectively. It is recommended that the accessors of dependency properties not contain additional logic because clients and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can bypass the accessors and call <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> directly. For example, when a property is bound to a data source, the property's `set` accessor is not called. Instead of adding additional logic to the get and set accessors, use the <xref:System.Windows.ValidateValueCallback>, <xref:System.Windows.CoerceValueCallback>, and <xref:System.Windows.PropertyChangedCallback> delegates to respond to or check the value when it changes. For more information on these callbacks, see [Dependency Property Callbacks and Validation](../advanced/dependency-property-callbacks-and-validation.md).
- Define a CLR wrapper property named `Value`, which is the same name that is used to register the dependency property, by implementing the property's `get` and `set` accessors. Note that the `get` and `set` accessors only call <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> respectively. It is recommended that the accessors of dependency properties not contain additional logic because clients and WPF can bypass the accessors and call <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> directly. For example, when a property is bound to a data source, the property's `set` accessor is not called. Instead of adding additional logic to the get and set accessors, use the <xref:System.Windows.ValidateValueCallback>, <xref:System.Windows.CoerceValueCallback>, and <xref:System.Windows.PropertyChangedCallback> delegates to respond to or check the value when it changes. For more information on these callbacks, see [Dependency Property Callbacks and Validation](../advanced/dependency-property-callbacks-and-validation.md).
- Define a method for the <xref:System.Windows.CoerceValueCallback> named `CoerceValue`. `CoerceValue` ensures that `Value` is greater or equal to `MinValue` and less than or equal to `MaxValue`.
@@ -133,13 +133,13 @@ For more information, see [Custom Dependency Properties](../advanced/custom-depe
### Use Routed Events
Just as dependency properties extend the notion of CLR properties with additional functionality, routed events extend the notion of standard CLR events. When you create a new [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control, it is also good practice to implement your event as a routed event because a routed event supports the following behavior:
Just as dependency properties extend the notion of CLR properties with additional functionality, routed events extend the notion of standard CLR events. When you create a new WPF control, it is also good practice to implement your event as a routed event because a routed event supports the following behavior:
- Events can be handled on a parent of multiple controls. If an event is a bubbling event, a single parent in the element tree can subscribe to the event. Then application authors can use one handler to respond to the event of multiple controls. For example, if your control is a part of each item in a <xref:System.Windows.Controls.ListBox> (because it is included in a <xref:System.Windows.DataTemplate>), the application developer can define the event handler for your control's event on the <xref:System.Windows.Controls.ListBox>. Whenever the event occurs on any of the controls, the event handler is called.
- Routed events can be used in an <xref:System.Windows.EventSetter>, which enables application developers to specify the handler of an event within a style.
- Routed events can be used in an <xref:System.Windows.EventTrigger>, which is useful for animating properties by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. For more information, see [Animation Overview](../graphics-multimedia/animation-overview.md).
- Routed events can be used in an <xref:System.Windows.EventTrigger>, which is useful for animating properties by using XAML. For more information, see [Animation Overview](../graphics-multimedia/animation-overview.md).
The following example defines a routed event by doing the following:
@@ -155,7 +155,7 @@ The following example defines a routed event by doing the following:
- The owning type of the event is `NumericUpDown`.
- Declare a public event named `ValueChanged` and includes event-accessor declarations. The example calls <xref:System.Windows.UIElement.AddHandler%2A> in the `add` accessor declaration and <xref:System.Windows.UIElement.RemoveHandler%2A> in the `remove` accessor declaration to use the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event services.
- Declare a public event named `ValueChanged` and includes event-accessor declarations. The example calls <xref:System.Windows.UIElement.AddHandler%2A> in the `add` accessor declaration and <xref:System.Windows.UIElement.RemoveHandler%2A> in the `remove` accessor declaration to use the WPF event services.
- Create a protected, virtual method named `OnValueChanged` that raises the `ValueChanged` event.
@@ -187,7 +187,7 @@ To receive support for custom WPF controls in the WPF Designer for Visual Studio
#### Dependency Properties
Be sure to implement CLR `get` and `set` accessors as described earlier, in "Use Dependency Properties." Designers may use the wrapper to detect the presence of a dependency property, but they, like [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and clients of the control, are not required to call the accessors when getting or setting the property.
Be sure to implement CLR `get` and `set` accessors as described earlier, in "Use Dependency Properties." Designers may use the wrapper to detect the presence of a dependency property, but they, like WPF and clients of the control, are not required to call the accessors when getting or setting the property.
#### Attached Properties
@@ -227,9 +227,9 @@ You can define shared resources at the element level by creating a custom resour
[!code-xaml[SharedResources#1](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/Dictionary1.xaml#1)]
Once you have defined your dictionary, you need to merge it with your control's resource dictionary. You can do this by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or code.
Once you have defined your dictionary, you need to merge it with your control's resource dictionary. You can do this by using XAML or code.
The following example merges a resource dictionary by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
The following example merges a resource dictionary by using XAML.
[!code-xaml[SharedResources#2](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/ShapeResizer.xaml#2)]
@@ -239,13 +239,13 @@ The following example creates a class that returns a shared <xref:System.Windows
[!code-csharp[SharedResources#3](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/SharedDictionaryManager.cs#3)]
The following example merges the shared resource with the resources of a custom control in the control's constructor before it calls `InitializeComponent`. Because the `SharedDictionaryManager.SharedDictionary` is a static property, the <xref:System.Windows.ResourceDictionary> is created only once. Because the resource dictionary was merged before `InitializeComponent` was called, the resources are available to the control in its [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file.
The following example merges the shared resource with the resources of a custom control in the control's constructor before it calls `InitializeComponent`. Because the `SharedDictionaryManager.SharedDictionary` is a static property, the <xref:System.Windows.ResourceDictionary> is created only once. Because the resource dictionary was merged before `InitializeComponent` was called, the resources are available to the control in its XAML file.
[!code-csharp[SharedResources#4](~/samples/snippets/csharp/VS_Snippets_Wpf/SharedResources/CS/ShapeResizer.xaml.cs#4)]
#### Defining Resources at the Theme Level
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables you to create resources for different Windows themes. As a control author, you can define a resource for a specific theme to change your control's appearance depending on what theme is in use. For example, the appearance of a <xref:System.Windows.Controls.Button> in the Windows Classic theme (the default theme for Windows 2000) differs from a <xref:System.Windows.Controls.Button> in the Windows Luna theme (the default theme for Windows XP) because the <xref:System.Windows.Controls.Button> uses a different <xref:System.Windows.Controls.ControlTemplate> for each theme.
WPF enables you to create resources for different Windows themes. As a control author, you can define a resource for a specific theme to change your control's appearance depending on what theme is in use. For example, the appearance of a <xref:System.Windows.Controls.Button> in the Windows Classic theme (the default theme for Windows 2000) differs from a <xref:System.Windows.Controls.Button> in the Windows Luna theme (the default theme for Windows XP) because the <xref:System.Windows.Controls.Button> uses a different <xref:System.Windows.Controls.ControlTemplate> for each theme.
Resources that are specific to a theme are kept in a resource dictionary with a specific file name. These files must be in a folder named `Themes` that is a subfolder of the folder that contains the control. The following table lists the resource dictionary files and the theme that is associated with each file:
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: a3d9930e-5597-470e-a636-dcf65eac500b
---
# Control Customization
This category covers the various base classes, interfaces and other elements and concepts used in creating a fully functional [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control.
This category covers the various base classes, interfaces and other elements and concepts used in creating a fully functional Windows Presentation Foundation (WPF) control.
## In This Section
[Control Authoring Overview](control-authoring-overview.md)
@@ -17,7 +17,7 @@ ms.assetid: 9e356d3d-a3d0-4b01-a25f-2d43e4d53fe5
# Creating a Control That Has a Customizable Appearance
<a name="introduction"></a>
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] gives you the ability to create a control whose appearance can be customized. For example, you can change the appearance of a <xref:System.Windows.Controls.CheckBox> beyond what setting properties will do by creating a new <xref:System.Windows.Controls.ControlTemplate>. The following illustration shows a <xref:System.Windows.Controls.CheckBox> that uses a default <xref:System.Windows.Controls.ControlTemplate> and a <xref:System.Windows.Controls.CheckBox> that uses a custom <xref:System.Windows.Controls.ControlTemplate>.
Windows Presentation Foundation (WPF) gives you the ability to create a control whose appearance can be customized. For example, you can change the appearance of a <xref:System.Windows.Controls.CheckBox> beyond what setting properties will do by creating a new <xref:System.Windows.Controls.ControlTemplate>. The following illustration shows a <xref:System.Windows.Controls.CheckBox> that uses a default <xref:System.Windows.Controls.ControlTemplate> and a <xref:System.Windows.Controls.CheckBox> that uses a custom <xref:System.Windows.Controls.ControlTemplate>.
![A checkbox with the default control template.](./media/ndp-checkboxdefault.png "NDP_CheckBoxDefault")
A CheckBox that uses the default control template
@@ -65,7 +65,7 @@ The parts and states model specifies how to define the visual structure and visu
- Provide a control contract to specify what should be included in the <xref:System.Windows.Controls.ControlTemplate>.
When you define the visual structure and visual behavior in the <xref:System.Windows.Controls.ControlTemplate> of a control, application authors can change the visual structure and visual behavior of your control by creating a new <xref:System.Windows.Controls.ControlTemplate> instead of writing code. You must provide a control contract that tells application authors which <xref:System.Windows.FrameworkElement> objects and states should be defined in the <xref:System.Windows.Controls.ControlTemplate>. You should follow some best practices when you interact with the parts in the <xref:System.Windows.Controls.ControlTemplate> so that your control properly handles an incomplete <xref:System.Windows.Controls.ControlTemplate>. If you follow these three principles, application authors will be able to create a <xref:System.Windows.Controls.ControlTemplate> for your control just as easily as they can for the controls that ship with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The following section explains each of these recommendations in detail.
When you define the visual structure and visual behavior in the <xref:System.Windows.Controls.ControlTemplate> of a control, application authors can change the visual structure and visual behavior of your control by creating a new <xref:System.Windows.Controls.ControlTemplate> instead of writing code. You must provide a control contract that tells application authors which <xref:System.Windows.FrameworkElement> objects and states should be defined in the <xref:System.Windows.Controls.ControlTemplate>. You should follow some best practices when you interact with the parts in the <xref:System.Windows.Controls.ControlTemplate> so that your control properly handles an incomplete <xref:System.Windows.Controls.ControlTemplate>. If you follow these three principles, application authors will be able to create a <xref:System.Windows.Controls.ControlTemplate> for your control just as easily as they can for the controls that ship with WPF. The following section explains each of these recommendations in detail.
<a name="defining_the_visual_structure_and_visual_behavior_of_a_control_in_a_controltemplate"></a>
@@ -30,7 +30,7 @@ An <xref:System.Windows.Controls.Expander> control provides a way to provide con
When you set a size dimension on an <xref:System.Windows.Controls.Expander> control in the direction that the expanded content is displayed, the <xref:System.Windows.Controls.Expander> takes control of the area that is used by the content and displays a border around it. The border shows even when the content is collapsed. To set the size of the expanded content area, set size dimensions on the content of the <xref:System.Windows.Controls.Expander>, or if you want scrolling capability, on the <xref:System.Windows.Controls.ScrollViewer> that encloses the content.
When an <xref:System.Windows.Controls.Expander> control is the last element in a <xref:System.Windows.Controls.DockPanel>, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] automatically sets the <xref:System.Windows.Controls.Expander> dimensions to equal the remaining area of the <xref:System.Windows.Controls.DockPanel>. To prevent this default behavior, set the <xref:System.Windows.Controls.DockPanel.LastChildFill%2A> property on the <xref:System.Windows.Controls.DockPanel> object to `false`, or make sure that the <xref:System.Windows.Controls.Expander> is not the last element in a <xref:System.Windows.Controls.DockPanel>.
When an <xref:System.Windows.Controls.Expander> control is the last element in a <xref:System.Windows.Controls.DockPanel>, Windows Presentation Foundation (WPF) automatically sets the <xref:System.Windows.Controls.Expander> dimensions to equal the remaining area of the <xref:System.Windows.Controls.DockPanel>. To prevent this default behavior, set the <xref:System.Windows.Controls.DockPanel.LastChildFill%2A> property on the <xref:System.Windows.Controls.DockPanel> object to `false`, or make sure that the <xref:System.Windows.Controls.Expander> is not the last element in a <xref:System.Windows.Controls.DockPanel>.
<a name="CreatingScrollableContent"></a>
## Creating Scrollable Content
@@ -8,7 +8,7 @@ ms.assetid: c52dde45-a311-4531-af4c-853371c4d5f4
---
# Guidelines for Designing Stylable Controls
This document summarizes a set of best practices to consider when designing a control which you intend to be easily stylable and templatable. We came to this set of best practices through a lot of trial and error while working on the theme control styles for the built-in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control set. We learned that successful styling is as much a function of a well-designed object model as it is of the style itself. The intended audience for this document is the control author, not the style author.
This document summarizes a set of best practices to consider when designing a control which you intend to be easily stylable and templatable. We came to this set of best practices through a lot of trial and error while working on the theme control styles for the built-in WPF control set. We learned that successful styling is as much a function of a well-designed object model as it is of the style itself. The intended audience for this document is the control author, not the style author.
<a name="Terminology"></a>
@@ -42,7 +42,7 @@ To understand your control's common usage, it's good to think about the value pr
- Minimize contracts as much as possible.
- Design around the expectation that during design time (that is, when using a design tool) it is common for a control template to be in an incomplete state. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not offer a "composing" state infrastructure, so controls have to be built with the expectation that such a state might be valid.
- Design around the expectation that during design time (that is, when using a design tool) it is common for a control template to be in an incomplete state. WPF does not offer a "composing" state infrastructure, so controls have to be built with the expectation that such a state might be valid.
- Do not throw exceptions when any aspect of a template contract is not followed. Along these lines, panels should not throw exceptions if they have too many or too few children.
@@ -101,7 +101,7 @@ To understand your control's common usage, it's good to think about the value pr
- **Be consistent with existing styling patterns.** Many times there are multiple ways to solve a problem. Be aware of and, when possible, consistent with existing control styling patterns. This is especially important for controls that derive from the same base type (for example, <xref:System.Windows.Controls.ContentControl>, <xref:System.Windows.Controls.ItemsControl>, <xref:System.Windows.Controls.Primitives.RangeBase>, and so on).
- **Expose properties to enable common customization scenarios without retemplating**. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not support pluggable/customizable parts, so a control user is left with only two methods of customization: setting properties directly or setting properties using styles. With that in mind, it is appropriate to surface a limited number of properties targeted at very common, high-priority customization scenarios which would otherwise require the retemplating. Here are best practices for when and how to enable customization scenarios:
- **Expose properties to enable common customization scenarios without retemplating**. WPF does not support pluggable/customizable parts, so a control user is left with only two methods of customization: setting properties directly or setting properties using styles. With that in mind, it is appropriate to surface a limited number of properties targeted at very common, high-priority customization scenarios which would otherwise require the retemplating. Here are best practices for when and how to enable customization scenarios:
- Very common customizations should be exposed as properties on the control and consumed by the template.
@@ -25,7 +25,7 @@ This example shows how to programmatically bind an adorner to the children of a
[!code-vb[Adorners_SimpleCircleAdorner#_AdornChildren](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Adorners_SimpleCircleAdorner/VisualBasic/Window1.xaml.vb#_adornchildren)]
> [!NOTE]
> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported.
> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported.
## See also
@@ -15,11 +15,11 @@ ms.assetid: b9c22ef4-bce4-4300-9e0c-8260b7db83cc
## Example
This example shows how to change the value of the <xref:System.Windows.Controls.Viewbox.StretchDirection%2A> and <xref:System.Windows.Controls.Viewbox.Stretch%2A> properties of a <xref:System.Windows.Controls.Viewbox>.
The first example uses [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a <xref:System.Windows.Controls.Viewbox> element. It assigns a <xref:System.Windows.FrameworkElement.MaxWidth%2A> and <xref:System.Windows.FrameworkElement.MaxHeight%2A> of 400. The example nests an <xref:System.Windows.Controls.Image> element within the <xref:System.Windows.Controls.Viewbox>. <xref:System.Windows.Controls.Button> elements that correspond to the property values for the <xref:System.Windows.Controls.Viewbox.Stretch%2A> and <xref:System.Windows.Controls.StretchDirection> enumerations manipulate the stretching behavior of the nested <xref:System.Windows.Controls.Image>.
The first example uses Extensible Application Markup Language (XAML) to define a <xref:System.Windows.Controls.Viewbox> element. It assigns a <xref:System.Windows.FrameworkElement.MaxWidth%2A> and <xref:System.Windows.FrameworkElement.MaxHeight%2A> of 400. The example nests an <xref:System.Windows.Controls.Image> element within the <xref:System.Windows.Controls.Viewbox>. <xref:System.Windows.Controls.Button> elements that correspond to the property values for the <xref:System.Windows.Controls.Viewbox.Stretch%2A> and <xref:System.Windows.Controls.StretchDirection> enumerations manipulate the stretching behavior of the nested <xref:System.Windows.Controls.Image>.
[!code-xaml[viewboxStretchLayoutSamp#1](~/samples/snippets/csharp/VS_Snippets_Wpf/viewboxStretchLayoutSamp/CSharp/Window1.xaml#1)]
The following code-behind file handles the <xref:System.Windows.Controls.Button> <xref:System.Windows.Controls.Primitives.ButtonBase.Click> events that the previous [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example defines.
The following code-behind file handles the <xref:System.Windows.Controls.Button> <xref:System.Windows.Controls.Primitives.ButtonBase.Click> events that the previous XAML example defines.
[!code-csharp[viewboxStretchLayoutSamp#2](~/samples/snippets/csharp/VS_Snippets_Wpf/viewboxStretchLayoutSamp/CSharp/Window1.xaml.cs#2)]
[!code-vb[viewboxStretchLayoutSamp#2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/viewboxStretchLayoutSamp/VisualBasic/Window1.xaml.vb#2)]
@@ -25,7 +25,7 @@ This example shows how to programmatically bind an adorner to a specified <xref:
[!code-vb[Adorners_SimpleCircleAdorner#_AdornSingleElement](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Adorners_SimpleCircleAdorner/VisualBasic/Window1.xaml.vb#_adornsingleelement)]
> [!NOTE]
> Using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to bind an adorner to another element is currently not supported.
> Using Extensible Application Markup Language (XAML) to bind an adorner to another element is currently not supported.
## See also
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: d6ac3d51-844b-4d29-96d8-81a696a7b960
---
# How to: Build a Standard UI Dialog Box by Using Grid
This example shows how to create a standard [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] dialog box by using the <xref:System.Windows.Controls.Grid> element.
This example shows how to create a standard user interface (UI) dialog box by using the <xref:System.Windows.Controls.Grid> element.
## Example
The following example creates a dialog box like the **Run** dialog box in the Windows operating system.
@@ -10,7 +10,7 @@ ms.assetid: b2f07626-9df8-43b8-8d36-492f3cb42837
---
# How to: Create a Grid Element
## Example
The following example shows how to create and use an instance of <xref:System.Windows.Controls.Grid> by using either [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. This example uses three <xref:System.Windows.Controls.ColumnDefinition> objects and three <xref:System.Windows.Controls.RowDefinition> objects to create a grid that has nine cells, such as in a worksheet. Each cell contains a <xref:System.Windows.Controls.TextBlock> element that represents data, and the top row contains a <xref:System.Windows.Controls.TextBlock> with the <xref:System.Windows.Controls.Grid.ColumnSpan%2A> property applied. To show the boundaries of each cell, the <xref:System.Windows.Controls.Grid.ShowGridLines%2A> property is enabled.
The following example shows how to create and use an instance of <xref:System.Windows.Controls.Grid> by using either Extensible Application Markup Language (XAML) or code. This example uses three <xref:System.Windows.Controls.ColumnDefinition> objects and three <xref:System.Windows.Controls.RowDefinition> objects to create a grid that has nine cells, such as in a worksheet. Each cell contains a <xref:System.Windows.Controls.TextBlock> element that represents data, and the top row contains a <xref:System.Windows.Controls.TextBlock> with the <xref:System.Windows.Controls.Grid.ColumnSpan%2A> property applied. To show the boundaries of each cell, the <xref:System.Windows.Controls.Grid.ShowGridLines%2A> property is enabled.
[!code-csharp[Grid#3](~/samples/snippets/csharp/VS_Snippets_Wpf/Grid/CSharp/Grid_Code.cs#3)]
[!code-vb[Grid#3](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Grid/VisualBasic/grid_vb.vb#3)]
@@ -7,7 +7,7 @@ helpviewer_keywords:
ms.assetid: 05914a93-d0ea-4a9a-b693-09df7d4e2ac2
---
# How to: Create a Multiline TextBox Control
This example shows how to use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a <xref:System.Windows.Controls.TextBox> control that will automatically expand to accommodate multiple lines of text.
This example shows how to use Extensible Application Markup Language (XAML) to define a <xref:System.Windows.Controls.TextBox> control that will automatically expand to accommodate multiple lines of text.
## Example
Setting the <xref:System.Windows.Controls.TextBox.TextWrapping%2A> attribute to **Wrap** will cause entered text to wrap to a new line when the edge of the <xref:System.Windows.Controls.TextBox> control is reached, automatically expanding the <xref:System.Windows.Controls.TextBox> control to include room for a new line, if necessary.
@@ -17,7 +17,7 @@ This example shows how to create and use an instance of <xref:System.Windows.Con
The following example explicitly positions two <xref:System.Windows.Controls.TextBlock> elements by using the <xref:System.Windows.Controls.Canvas.SetTop%2A> and <xref:System.Windows.Controls.Canvas.SetLeft%2A> methods of <xref:System.Windows.Controls.Canvas>. The example also assigns a <xref:System.Windows.Controls.Control.Background%2A> color of `LightSteelBlue` to the <xref:System.Windows.Controls.Canvas>.
> [!NOTE]
> When you use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to position <xref:System.Windows.Controls.TextBlock> elements, use the <xref:System.Windows.Controls.Canvas.Top%2A> and <xref:System.Windows.Controls.Canvas.Left%2A> properties.
> When you use Extensible Application Markup Language (XAML) to position <xref:System.Windows.Controls.TextBlock> elements, use the <xref:System.Windows.Controls.Canvas.Top%2A> and <xref:System.Windows.Controls.Canvas.Left%2A> properties.
[!code-csharp[CanvasCode#1](~/samples/snippets/csharp/VS_Snippets_Wpf/CanvasCode/CSharp/Canvas_Code.cs#1)]
[!code-vb[CanvasCode#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CanvasCode/VisualBasic/canvas_vb.vb#1)]
@@ -14,7 +14,7 @@ ms.assetid: 5ab75911-e36a-4825-80e4-081c57e8e182
The example also defines a second custom method, called `changeColVal`. This custom method converts the <xref:System.Windows.Controls.Primitives.RangeBase.Value%2A> of a <xref:System.Windows.Controls.Slider> to a <xref:System.String> and then passes that value back to the <xref:System.Windows.Controls.ColumnDefinition> as the <xref:System.Windows.Controls.ColumnDefinition.Width%2A> of the element.
Note that a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file defines the contents of a <xref:System.Windows.Controls.ListBoxItem>.
Note that a separate Extensible Application Markup Language (XAML) file defines the contents of a <xref:System.Windows.Controls.ListBoxItem>.
[!code-csharp[gridlengthConverterGrid#1](~/samples/snippets/csharp/VS_Snippets_Wpf/gridlengthConverterGrid/CSharp/Window1.xaml.cs#1)]
[!code-vb[gridlengthConverterGrid#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/gridlengthConverterGrid/VisualBasic/Window1.xaml.vb#1)]
@@ -17,7 +17,7 @@ This example shows how to crop an image using <xref:System.Windows.Media.Imaging
## Example
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] defines resources used within the samples below.
The following Extensible Application Markup Language (XAML) defines resources used within the samples below.
[!code-xaml[imageelementexample#CroppedXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/ImageElementExample/CSharp/CroppedImageExample.xaml#croppedxaml1)]
@@ -16,7 +16,7 @@ ms.assetid: 1c39ee14-e37f-49fb-a0d1-a9824ca13584
This example shows one way to use the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> event to execute a method whenever the text in a <xref:System.Windows.Controls.TextBox> control has changed.
In the code-behind class for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that contains the <xref:System.Windows.Controls.TextBox> control that you want to monitor for changes, insert a method to call whenever the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> event fires. This method must have a signature that matches what is expected by the <xref:System.Windows.Controls.TextChangedEventHandler> delegate.
In the code-behind class for the XAML that contains the <xref:System.Windows.Controls.TextBox> control that you want to monitor for changes, insert a method to call whenever the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> event fires. This method must have a signature that matches what is expected by the <xref:System.Windows.Controls.TextChangedEventHandler> delegate.
The event handler is called whenever the contents of the <xref:System.Windows.Controls.TextBox> control are changed, either by a user or programmatically.
@@ -25,13 +25,13 @@ The event handler is called whenever the contents of the <xref:System.Windows.Co
## Define TextBox control
In the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that defines your <xref:System.Windows.Controls.TextBox> control, specify the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> attribute with a value that matches the event handler method name.
In the Extensible Application Markup Language (XAML) that defines your <xref:System.Windows.Controls.TextBox> control, specify the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> attribute with a value that matches the event handler method name.
[!code-xaml[TextBox_MiscCode#_TextChangedXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textchangedxaml)]
## Monitor the TextBox control changes
In the code-behind class for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that contains the <xref:System.Windows.Controls.TextBox> control that you want to monitor for changes, insert a method to call whenever the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> event fires. This method must have a signature that matches what is expected by the <xref:System.Windows.Controls.TextChangedEventHandler> delegate.
In the code-behind class for the XAML that contains the <xref:System.Windows.Controls.TextBox> control that you want to monitor for changes, insert a method to call whenever the <xref:System.Windows.Controls.Primitives.TextBoxBase.TextChanged> event fires. This method must have a signature that matches what is expected by the <xref:System.Windows.Controls.TextChangedEventHandler> delegate.
[!code-csharp[TextBox_MiscCode#_TextChangedEventHandler](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml.cs#_textchangedeventhandler)]
[!code-vb[TextBox_MiscCode#_TextChangedEventHandler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextBox_MiscCode/VisualBasic/Window1.xaml.vb#_textchangedeventhandler)]
@@ -17,7 +17,7 @@ ms.assetid: f13c093f-1a05-45b3-ac8f-c9ea5e4a11c5
This example shows how to extract the contents of a <xref:System.Windows.Controls.RichTextBox> as plain text.
## Describe a RichTextBox control
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a named <xref:System.Windows.Controls.RichTextBox> control with simple content.
The following Extensible Application Markup Language (XAML) code describes a named <xref:System.Windows.Controls.RichTextBox> control with simple content.
[!code-xaml[RichTextBoxSnippets#_RTB_XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/RichTextBoxSnippets/CSharp/Window1.xaml#_rtb_xaml)]
@@ -13,7 +13,7 @@ ms.assetid: 42c695d8-ee28-49d4-80fd-fc71e9be7f29
## Example
This example shows how to handle the <xref:System.Windows.Controls.ScrollViewer.ScrollChanged> event of a <xref:System.Windows.Controls.ScrollViewer>.
A <xref:System.Windows.Documents.FlowDocument> element with <xref:System.Windows.Documents.Paragraph> parts is defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. When the <xref:System.Windows.Controls.ScrollViewer.ScrollChanged> event occurs due to user interaction, a handler is invoked, and text is written to a <xref:System.Windows.Controls.TextBlock> indicating that the event has occurred.
A <xref:System.Windows.Documents.FlowDocument> element with <xref:System.Windows.Documents.Paragraph> parts is defined in XAML. When the <xref:System.Windows.Controls.ScrollViewer.ScrollChanged> event occurs due to user interaction, a handler is invoked, and text is written to a <xref:System.Windows.Controls.TextBlock> indicating that the event has occurred.
[!code-xaml[scrollchangedeventargsLayout#1](~/samples/snippets/csharp/VS_Snippets_Wpf/scrollchangedeventargsLayout/CSharp/Window1.xaml#1)]
[!code-xaml[scrollchangedeventargsLayout#2](~/samples/snippets/csharp/VS_Snippets_Wpf/scrollchangedeventargsLayout/CSharp/Window1.xaml#2)]
@@ -15,7 +15,7 @@ ms.assetid: c1e8f962-72c8-4e7a-8670-7a2d7e021791
This example shows how to adjust the <xref:System.Windows.Controls.StackPanel.Orientation%2A> of content within a <xref:System.Windows.Controls.StackPanel> element, and also how to adjust the <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A> and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> of child content.
## Example
The following example creates three <xref:System.Windows.Controls.ListBox> elements in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. Each <xref:System.Windows.Controls.ListBox> represents the possible values of the <xref:System.Windows.Controls.StackPanel.Orientation%2A>, <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> properties of a <xref:System.Windows.Controls.StackPanel>. When a user selects a value in any of the <xref:System.Windows.Controls.ListBox> elements, the associated property of the <xref:System.Windows.Controls.StackPanel> and its child <xref:System.Windows.Controls.Button> elements change.
The following example creates three <xref:System.Windows.Controls.ListBox> elements in Extensible Application Markup Language (XAML). Each <xref:System.Windows.Controls.ListBox> represents the possible values of the <xref:System.Windows.Controls.StackPanel.Orientation%2A>, <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> properties of a <xref:System.Windows.Controls.StackPanel>. When a user selects a value in any of the <xref:System.Windows.Controls.ListBox> elements, the associated property of the <xref:System.Windows.Controls.StackPanel> and its child <xref:System.Windows.Controls.Button> elements change.
[!code-xaml[StackPanelIntroSamp#1](~/samples/snippets/csharp/VS_Snippets_Wpf/StackPanelIntroSamp/CSharp/Window1.xaml#1)]
@@ -14,7 +14,7 @@ This example shows how to configure a <xref:System.Windows.Controls.TextBox> con
[!code-xaml[TextBox_MiscCode#_ReadOnlyTextBoxXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_readonlytextboxxaml)]
The <xref:System.Windows.Controls.Primitives.TextBoxBase.IsReadOnly%2A> attribute affects user input only; it does not affect text set in the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] description of a <xref:System.Windows.Controls.TextBox> control, or text set programmatically through the <xref:System.Windows.Controls.TextBox.Text%2A> property.
The <xref:System.Windows.Controls.Primitives.TextBoxBase.IsReadOnly%2A> attribute affects user input only; it does not affect text set in the Extensible Application Markup Language (XAML) description of a <xref:System.Windows.Controls.TextBox> control, or text set programmatically through the <xref:System.Windows.Controls.TextBox.Text%2A> property.
The default value of <xref:System.Windows.Controls.Primitives.TextBoxBase.IsReadOnly%2A> is **false**.
@@ -12,7 +12,7 @@ helpviewer_keywords:
ms.assetid: a219b9e5-b205-4438-89b5-0a137ac463ab
---
# How to: Partition Space by Using the DockPanel Element
The following example creates a simple [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] framework using a <xref:System.Windows.Controls.DockPanel> element. The <xref:System.Windows.Controls.DockPanel> partitions available space to its child elements.
The following example creates a simple user interface (UI) framework using a <xref:System.Windows.Controls.DockPanel> element. The <xref:System.Windows.Controls.DockPanel> partitions available space to its child elements.
## Example
This example uses the <xref:System.Windows.Controls.DockPanel.Dock%2A> property, which is an attached property, to dock two identical <xref:System.Windows.Controls.Border> elements at the <xref:System.Windows.Controls.Dock.Top> of the partitioned space. A third <xref:System.Windows.Controls.Border> element is docked to the <xref:System.Windows.Controls.Dock.Left>, with its width set to 200 pixels. A fourth <xref:System.Windows.Controls.Border> is docked to the <xref:System.Windows.Controls.Dock.Bottom> of the screen. The last <xref:System.Windows.Controls.Border> element automatically fills the remaining space.
@@ -27,7 +27,7 @@ This example shows how to specify the position of a tooltip on the screen.
If you define the contents of a tooltip by using a <xref:System.Windows.Controls.ToolTip> object, you can use the properties of either class; however, the <xref:System.Windows.Controls.ToolTipService> properties take precedence. Use the <xref:System.Windows.Controls.ToolTipService> properties for tooltips that are not defined as <xref:System.Windows.Controls.ToolTip> objects.
The following illustrations show how to position a tooltip by using these properties. Although, the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples in these illustrations show how to set the properties that are defined by the <xref:System.Windows.Controls.ToolTip> class, the corresponding properties of the <xref:System.Windows.Controls.ToolTipService> class follow the same layout rules. For more information about the possible values for the Placement property, see [Popup Placement Behavior](popup-placement-behavior.md).
The following illustrations show how to position a tooltip by using these properties. Although, the Extensible Application Markup Language (XAML) examples in these illustrations show how to set the properties that are defined by the <xref:System.Windows.Controls.ToolTip> class, the corresponding properties of the <xref:System.Windows.Controls.ToolTipService> class follow the same layout rules. For more information about the possible values for the Placement property, see [Popup Placement Behavior](popup-placement-behavior.md).
The following image shows tooltip placement by using the Placement property:
@@ -16,14 +16,14 @@ ms.assetid: d5793172-1e11-4a39-9be0-73f336ed858d
This example shows one way to use the <xref:System.Windows.Controls.TextBox.SelectedText%2A> property to retrieve text that the user has selected in a <xref:System.Windows.Controls.TextBox> control.
## Define a TextBox control
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example shows the definition of a <xref:System.Windows.Controls.TextBox> control that contains some text to select, and a <xref:System.Windows.Controls.Button> control with a specified <xref:System.Windows.Controls.Button.OnClick%2A> method.
The following Extensible Application Markup Language (XAML) example shows the definition of a <xref:System.Windows.Controls.TextBox> control that contains some text to select, and a <xref:System.Windows.Controls.Button> control with a specified <xref:System.Windows.Controls.Button.OnClick%2A> method.
In this example, a button with an associated <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event handler is used to retrieve the text selection. When the user clicks the button, the <xref:System.Windows.Controls.Button.OnClick%2A> method copies any selected text in the textbox into a string. The particular circumstances by which the text selection is retrieved (clicking a button), as well as the action taken with that selection (copying the text selection to a string), can easily be modified to accommodate a wide variety of scenarios.
[!code-xaml[TextBox_MiscCode#_TextBoxSelectTextXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textboxselecttextxaml)]
## OnClick event handler
The following C# example shows an <xref:System.Windows.Controls.Button.OnClick%2A> event handler for the button defined in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] for this example.
The following C# example shows an <xref:System.Windows.Controls.Button.OnClick%2A> event handler for the button defined in the XAML for this example.
[!code-csharp[TextBox_MiscCode#_SelectText](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml.cs#_selecttext)]
[!code-vb[TextBox_MiscCode#_SelectText](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextBox_MiscCode/VisualBasic/Window1.xaml.vb#_selecttext)]
@@ -14,11 +14,11 @@ ms.assetid: d8700bef-a3f8-4c12-9de2-fc3b79f32cd3
This example shows how to scroll content by using the <xref:System.Windows.Controls.Primitives.IScrollInfo> interface.
## Example
The following example demonstrates the features of the <xref:System.Windows.Controls.Primitives.IScrollInfo> interface. The example creates a <xref:System.Windows.Controls.StackPanel> element in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that is nested in a parent <xref:System.Windows.Controls.ScrollViewer>. The child elements of the <xref:System.Windows.Controls.StackPanel> can be scrolled logically by using the methods defined by the <xref:System.Windows.Controls.Primitives.IScrollInfo> interface and cast to the instance of <xref:System.Windows.Controls.StackPanel> (`sp1`) in code.
The following example demonstrates the features of the <xref:System.Windows.Controls.Primitives.IScrollInfo> interface. The example creates a <xref:System.Windows.Controls.StackPanel> element in Extensible Application Markup Language (XAML) that is nested in a parent <xref:System.Windows.Controls.ScrollViewer>. The child elements of the <xref:System.Windows.Controls.StackPanel> can be scrolled logically by using the methods defined by the <xref:System.Windows.Controls.Primitives.IScrollInfo> interface and cast to the instance of <xref:System.Windows.Controls.StackPanel> (`sp1`) in code.
[!code-xaml[IScrollInfoMethods#2](~/samples/snippets/csharp/VS_Snippets_Wpf/IScrollInfoMethods/CSharp/Window1.xaml#2)]
Each <xref:System.Windows.Controls.Button> in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file triggers an associated custom method that controls scrolling behavior in <xref:System.Windows.Controls.StackPanel>. The following example shows how to use the <xref:System.Windows.Controls.Primitives.IScrollInfo.LineUp%2A> and <xref:System.Windows.Controls.Primitives.IScrollInfo.LineDown%2A> methods; it also generically shows how to use all the positioning methods that the <xref:System.Windows.Controls.Primitives.IScrollInfo> class defines.
Each <xref:System.Windows.Controls.Button> in the XAML file triggers an associated custom method that controls scrolling behavior in <xref:System.Windows.Controls.StackPanel>. The following example shows how to use the <xref:System.Windows.Controls.Primitives.IScrollInfo.LineUp%2A> and <xref:System.Windows.Controls.Primitives.IScrollInfo.LineDown%2A> methods; it also generically shows how to use all the positioning methods that the <xref:System.Windows.Controls.Primitives.IScrollInfo> class defines.
[!code-csharp[IScrollInfoMethods#3](~/samples/snippets/csharp/VS_Snippets_Wpf/IScrollInfoMethods/CSharp/Window1.xaml.cs#3)]
[!code-vb[IScrollInfoMethods#3](~/samples/snippets/visualbasic/VS_Snippets_Wpf/IScrollInfoMethods/VisualBasic/Window1.xaml.vb#3)]
@@ -15,7 +15,7 @@ ms.assetid: 24b61b45-dc2d-425e-9839-b017af7ab86f
This example shows how to use the <xref:System.Windows.UIElement.Focus%2A> method to set focus on a <xref:System.Windows.Controls.TextBox> control.
## Define a simple TextBox control
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example describes a simple <xref:System.Windows.Controls.TextBox> control named *tbFocusMe*
The following Extensible Application Markup Language (XAML) example describes a simple <xref:System.Windows.Controls.TextBox> control named *tbFocusMe*
[!code-xaml[TextBox_MiscCode#_TextBoxFocusXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_textboxfocusxaml)]
@@ -11,11 +11,11 @@ ms.assetid: 5ab9e781-dbb8-469a-a3c8-cf38ce312647
---
# How to: Set the Height Properties of an Element
## Example
This example visually shows the differences in rendering behavior among the four height-related properties in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
This example visually shows the differences in rendering behavior among the four height-related properties in Windows Presentation Foundation (WPF).
The <xref:System.Windows.FrameworkElement> class exposes four properties that describe the height characteristics of an element. These four properties can conflict, and when they do, the value that takes precedence is determined as follows: the <xref:System.Windows.FrameworkElement.MinHeight%2A> value takes precedence over the <xref:System.Windows.FrameworkElement.MaxHeight%2A> value, which in turn takes precedence over the <xref:System.Windows.FrameworkElement.Height%2A> value. A fourth property, <xref:System.Windows.FrameworkElement.ActualHeight%2A>, is read-only, and reports the actual height as determined by interactions with the layout process.
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples draw a <xref:System.Windows.Shapes.Rectangle> element (`rect1`) as a child of <xref:System.Windows.Controls.Canvas>. You can change the height properties of a <xref:System.Windows.Shapes.Rectangle> by using a series of <xref:System.Windows.Controls.ListBox> elements that represent the property values of <xref:System.Windows.FrameworkElement.MinHeight%2A>, <xref:System.Windows.FrameworkElement.MaxHeight%2A>, and <xref:System.Windows.FrameworkElement.Height%2A>. In this manner, the precedence of each property is visually displayed.
The following Extensible Application Markup Language (XAML) examples draw a <xref:System.Windows.Shapes.Rectangle> element (`rect1`) as a child of <xref:System.Windows.Controls.Canvas>. You can change the height properties of a <xref:System.Windows.Shapes.Rectangle> by using a series of <xref:System.Windows.Controls.ListBox> elements that represent the property values of <xref:System.Windows.FrameworkElement.MinHeight%2A>, <xref:System.Windows.FrameworkElement.MaxHeight%2A>, and <xref:System.Windows.FrameworkElement.Height%2A>. In this manner, the precedence of each property is visually displayed.
[!code-xaml[HeightMinHeightMaxHeight#1](~/samples/snippets/csharp/VS_Snippets_Wpf/HeightMinHeightMaxHeight/CSharp/Window1.xaml#1)]
[!code-xaml[HeightMinHeightMaxHeight#2](~/samples/snippets/csharp/VS_Snippets_Wpf/HeightMinHeightMaxHeight/CSharp/Window1.xaml#2)]
@@ -16,7 +16,7 @@ ms.assetid: bcd25fc7-a52f-4453-b802-2c8d2b335ab8
This example shows how to use the <xref:System.Windows.Controls.TextBox.Text%2A> property to set the initial text contents of a <xref:System.Windows.Controls.TextBox> control.
> [!NOTE]
> Although the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] version of the example could use the `<TextBox.Text>` tags around the text of each button's <xref:System.Windows.Controls.TextBox> content, it is not necessary because the <xref:System.Windows.Controls.TextBox> applies the <xref:System.Windows.Markup.ContentPropertyAttribute> attribute to the <xref:System.Windows.Controls.TextBox.Text%2A> property. For more information, see [XAML in WPF](../advanced/xaml-in-wpf.md).
> Although the Extensible Application Markup Language (XAML) version of the example could use the `<TextBox.Text>` tags around the text of each button's <xref:System.Windows.Controls.TextBox> content, it is not necessary because the <xref:System.Windows.Controls.TextBox> applies the <xref:System.Windows.Markup.ContentPropertyAttribute> attribute to the <xref:System.Windows.Controls.TextBox.Text%2A> property. For more information, see [XAML in WPF](../advanced/xaml-in-wpf.md).
## Use the Text property to set the text contents
@@ -11,11 +11,11 @@ ms.assetid: 6ee04a9d-63f0-4f5b-a406-0a8cd4c35729
---
# How to: Set the Width Properties of an Element
## Example
This example visually shows the differences in rendering behavior among the four width-related properties in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
This example visually shows the differences in rendering behavior among the four width-related properties in Windows Presentation Foundation (WPF).
The <xref:System.Windows.FrameworkElement> class exposes four properties that describe the width characteristics of an element. These four properties can conflict, and when they do, the value that takes precedence is determined as follows: the <xref:System.Windows.FrameworkElement.MinWidth%2A> value takes precedence over the <xref:System.Windows.FrameworkElement.MaxWidth%2A> value, which in turn takes precedence over the <xref:System.Windows.FrameworkElement.Width%2A> value. A fourth property, <xref:System.Windows.FrameworkElement.ActualWidth%2A>, is read-only, and reports the actual width as determined by interactions with the layout process.
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples draw a <xref:System.Windows.Shapes.Rectangle> element (`rect1`) as a child of <xref:System.Windows.Controls.Canvas>. You can change the width properties of a <xref:System.Windows.Shapes.Rectangle> by using a series of <xref:System.Windows.Controls.ListBox> elements that represent the property values of <xref:System.Windows.FrameworkElement.MinWidth%2A>, <xref:System.Windows.FrameworkElement.MaxWidth%2A>, and <xref:System.Windows.FrameworkElement.Width%2A>. In this manner, the precedence of each property is visually displayed.
The following Extensible Application Markup Language (XAML) examples draw a <xref:System.Windows.Shapes.Rectangle> element (`rect1`) as a child of <xref:System.Windows.Controls.Canvas>. You can change the width properties of a <xref:System.Windows.Shapes.Rectangle> by using a series of <xref:System.Windows.Controls.ListBox> elements that represent the property values of <xref:System.Windows.FrameworkElement.MinWidth%2A>, <xref:System.Windows.FrameworkElement.MaxWidth%2A>, and <xref:System.Windows.FrameworkElement.Width%2A>. In this manner, the precedence of each property is visually displayed.
[!code-xaml[WidthMinWidthMaxWidth#1](~/samples/snippets/csharp/VS_Snippets_Wpf/WidthMinWidthMaxWidth/CSharp/Window1.xaml#1)]
[!code-xaml[WidthMinWidthMaxWidth#2](~/samples/snippets/csharp/VS_Snippets_Wpf/WidthMinWidthMaxWidth/CSharp/Window1.xaml#2)]
@@ -55,7 +55,7 @@ The following example shows the data items that are defined as an <xref:System.C
</ListView.ItemsSource>
```
The `s` and `p` identifiers in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] tags refer to namespace mappings that are defined in the metadata of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page. The following example shows the metadata definition.
The `s` and `p` identifiers in the XAML tags refer to namespace mappings that are defined in the metadata of the XAML page. The following example shows the metadata definition.
```xaml
<Window
@@ -17,7 +17,7 @@ ms.assetid: 842d3cd5-6fa0-4be4-8d90-6c7466213b1c
This example shows how to define and implement a simple custom context menu for a <xref:System.Windows.Controls.TextBox>.
## Define a Custom Context Menu
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example defines a <xref:System.Windows.Controls.TextBox> control that includes a custom context menu.
The following Extensible Application Markup Language (XAML) example defines a <xref:System.Windows.Controls.TextBox> control that includes a custom context menu.
The context menu is defined using a <xref:System.Windows.Controls.ContextMenu> element. The context menu itself consists of a series of <xref:System.Windows.Controls.MenuItem> elements and <xref:System.Windows.Controls.Separator> elements. Each <xref:System.Windows.Controls.MenuItem> element defines a command in the context menu; the <xref:System.Windows.Controls.HeaderedItemsControl.Header%2A> attribute defines the display text for the menu command, and the <xref:System.Windows.Controls.MenuItem.Click> attribute specifies a handler method for each menu item. The <xref:System.Windows.Controls.Separator> element simply causes a separating line to be rendered between the previous and subsequent menu items.
@@ -16,7 +16,7 @@ ms.assetid: 61f69a20-2ff3-4056-9060-e32f4483ec5e
By default, when you enable spell checking in an editing control like <xref:System.Windows.Controls.TextBox> or <xref:System.Windows.Controls.RichTextBox>, you get spell-checking choices in the context menu. For example, when users right-click a misspelled word, they get a set of spelling suggestions or the option to **Ignore All**. However, when you override the default context menu with your own custom context menu, this functionality is lost, and you need to write code to reenable the spell-checking feature in the context menu. The following example shows how to enable this on a <xref:System.Windows.Controls.TextBox>.
## Define a Context Menu
The following example shows the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that creates a <xref:System.Windows.Controls.TextBox> with some events that are used to implement the context menu.
The following example shows the Extensible Application Markup Language (XAML) that creates a <xref:System.Windows.Controls.TextBox> with some events that are used to implement the context menu.
[!code-xaml[TextBoxMiscSnippets_snip#SpellerCustomContextMenuExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBoxMiscSnippets_snip/csharp/speller_custom_context_menu.xaml#spellercustomcontextmenuexamplewholepage)]
@@ -14,7 +14,7 @@ ms.assetid: 4708cc65-6510-45f8-82e6-30b0d3e30045
This example shows how to use the scrolling methods of the <xref:System.Windows.Controls.ScrollViewer> element. These methods provide incremental scrolling of content, either by line or by page, in a <xref:System.Windows.Controls.ScrollViewer>.
## Example
The following example creates a <xref:System.Windows.Controls.ScrollViewer> named `sv1`, which hosts a child <xref:System.Windows.Controls.TextBlock> element. Because the <xref:System.Windows.Controls.TextBlock> is larger than the parent <xref:System.Windows.Controls.ScrollViewer>, scroll bars appear in order to enable scrolling. <xref:System.Windows.Controls.Button> elements that represent the various scrolling methods are docked on the left in a separate <xref:System.Windows.Controls.StackPanel>. Each <xref:System.Windows.Controls.Button> in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file calls a related custom method that controls scrolling behavior in <xref:System.Windows.Controls.ScrollViewer>.
The following example creates a <xref:System.Windows.Controls.ScrollViewer> named `sv1`, which hosts a child <xref:System.Windows.Controls.TextBlock> element. Because the <xref:System.Windows.Controls.TextBlock> is larger than the parent <xref:System.Windows.Controls.ScrollViewer>, scroll bars appear in order to enable scrolling. <xref:System.Windows.Controls.Button> elements that represent the various scrolling methods are docked on the left in a separate <xref:System.Windows.Controls.StackPanel>. Each <xref:System.Windows.Controls.Button> in the XAML file calls a related custom method that controls scrolling behavior in <xref:System.Windows.Controls.ScrollViewer>.
[!code-xaml[ScrollViewerMethods#1](~/samples/snippets/csharp/VS_Snippets_Wpf/ScrollViewerMethods/CSharp/Window1.xaml#1)]
@@ -16,7 +16,7 @@ ms.assetid: 5b92e74b-1b56-4756-ac64-d5e9e08d9854
This example shows how to include images in an application by using the <xref:System.Windows.Controls.Image> element.
## Define an image
The following example shows how to render an image 200 pixels wide. In this [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md). A <xref:System.Windows.Media.Imaging.BitmapImage> is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the <xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A> of the <xref:System.Windows.Media.Imaging.BitmapImage> is set to the same width as the <xref:System.Windows.FrameworkElement.Width%2A> of the <xref:System.Windows.Controls.Image>. This is done to ensure that the minimum amount of memory is used rendering the image.
The following example shows how to render an image 200 pixels wide. In this Extensible Application Markup Language (XAML) example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see [Dependency Properties Overview](../advanced/dependency-properties-overview.md). A <xref:System.Windows.Media.Imaging.BitmapImage> is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the <xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A> of the <xref:System.Windows.Media.Imaging.BitmapImage> is set to the same width as the <xref:System.Windows.FrameworkElement.Width%2A> of the <xref:System.Windows.Controls.Image>. This is done to ensure that the minimum amount of memory is used rendering the image.
> [!NOTE]
> In general, if you want to specify the size of a rendered image, specify only the <xref:System.Windows.FrameworkElement.Width%2A> or the <xref:System.Windows.FrameworkElement.Height%2A> but not both. If you only specify one, the image's aspect ratio is preserved. Otherwise, the image may unexpectedly appear stretched or warped. To control the image's stretching behavior, use the <xref:System.Windows.Controls.Image.Stretch%2A> and <xref:System.Windows.Controls.Image.StretchDirection%2A> properties.
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: 5707e860-ee4a-4c9f-b123-80c64996af19
---
# Image
The <xref:System.Windows.Controls.Image> element is used to display bitmap images in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications.
The <xref:System.Windows.Controls.Image> element is used to display bitmap images in Windows Presentation Foundation (WPF) applications.
## In This Section
[How-to Topics](image-how-to-topics.md)
@@ -11,15 +11,15 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
---
# Controls
<a name="introduction"></a>
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] ships with many of the common UI components that are used in almost every Windows application, 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 have been referred to as controls. While the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] SDK continues to use the term "control" to loosely mean any class that represents a visible object in an application, it is important to note that a class does not need to inherit from the <xref:System.Windows.Controls.Control> class to have a visible presence. Classes that inherit from the <xref:System.Windows.Controls.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 topic discusses how controls (both those that do inherit from the <xref:System.Windows.Controls.Control> class and those that do not) are commonly used in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
WPF SDK continues to use the term "control" to loosely mean any class that represents a visible object in an application, it is important to note that a class does not need to inherit from the <xref:System.Windows.Controls.Control> class to have a visible presence. Classes that inherit from the <xref:System.Windows.Controls.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 topic discusses how controls (both those that do inherit from the <xref:System.Windows.Controls.Control> class and those that do not) are commonly used in WPF.
<a name="creating_an_instance_of_a_control"></a>
## Creating an Instance of a Control
You can add a control to an application by using either [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. The following example shows how to create a simple application that asks a user for their first and last name. This example creates six controls: two labels, two text boxes, and two buttons, in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. All controls can be created similarly.
You can add a control to an application by using either XAML. All controls can be created similarly.
[!code-xaml[ControlsOverview#1](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/Window1.xaml#1)]
The following example creates the same application in code. For brevity, the creation of the <xref:System.Windows.Controls.Grid>, `grid1`, has been excluded from the sample. `grid1` has the same column and row definitions as shown in the preceding [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example.
The following example creates the same application in code. For brevity, the creation of the <xref:System.Windows.Controls.Grid>, `grid1`, has been excluded from the sample. `grid1` has the same column and row definitions as shown in the preceding XAML example.
[!code-csharp[ControlsOverview#2](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml.cs#2)]
[!code-vb[ControlsOverview#2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ControlsOverview/VisualBasic/AppInCode.xaml.vb#2)]
@@ -35,7 +35,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
- Create a new <xref:System.Windows.Controls.ControlTemplate> for the control.
### Changing a Control's Property Value
Many controls have properties that allow you to change how the control appears, such as the <xref:System.Windows.Controls.Control.Background%2A> of a <xref:System.Windows.Controls.Button>. You can set the value properties in both [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] 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 <xref:System.Windows.Controls.Button> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
Many controls have properties that allow you to change how the control appears, such as the <xref:System.Windows.Controls.Control.Background%2A> of a <xref:System.Windows.Controls.Button>. 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 <xref:System.Windows.Controls.Button> in XAML.
[!code-xaml[ControlsOverview#3](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml#3)]
@@ -45,7 +45,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
[!code-vb[ControlsOverview#4](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ControlsOverview/VisualBasic/AppInCode.xaml.vb#4)]
### Creating a Style for a Control
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] gives you the ability to specify the appearance of controls wholesale, instead of setting properties on each instance in the application, by creating a <xref:System.Windows.Style>. The following example creates a <xref:System.Windows.Style> that is applied to each <xref:System.Windows.Controls.Button> in the application. <xref:System.Windows.Style> definitions are typically defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] in a <xref:System.Windows.ResourceDictionary>, such as the <xref:System.Windows.FrameworkElement.Resources%2A> property of the <xref:System.Windows.FrameworkElement>.
WPF gives you the ability to specify the appearance of controls wholesale, instead of setting properties on each instance in the application, by creating a <xref:System.Windows.Style>. The following example creates a <xref:System.Windows.Style> that is applied to each <xref:System.Windows.Controls.Button> in the application. <xref:System.Windows.Style> definitions are typically defined in XAML in a <xref:System.Windows.ResourceDictionary>, such as the <xref:System.Windows.FrameworkElement.Resources%2A> property of the <xref:System.Windows.FrameworkElement>.
[!code-xaml[ControlsOverview#5](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/AppInCode.xaml#5)]
@@ -54,7 +54,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
### Creating a ControlTemplate
A <xref:System.Windows.Style> allows you to set properties on multiple controls at a time, but sometimes you might want to customize the appearance of a <xref:System.Windows.Controls.Control> beyond what you can do by creating 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 <xref:System.Windows.Controls.Control>. The <xref:System.Windows.Controls.Control.Template%2A> property of a <xref:System.Windows.Controls.Control> is public, so you can give a <xref:System.Windows.Controls.Control> a <xref:System.Windows.Controls.ControlTemplate> that is different than its default. You can often specify a new <xref:System.Windows.Controls.ControlTemplate> for a <xref:System.Windows.Controls.Control> instead of inheriting from a control to customize the appearance of a <xref:System.Windows.Controls.Control>.
Consider the very common control, <xref:System.Windows.Controls.Button>. The primary behavior of a <xref:System.Windows.Controls.Button> is to enable an application to take some action when the user clicks it. By default, the <xref:System.Windows.Controls.Button> in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] appears as a raised rectangle. While developing an application, you might want to take advantage of the behavior of a <xref:System.Windows.Controls.Button>--that is, by handling the button's click event--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>.
Consider the very common control, <xref:System.Windows.Controls.Button>. The primary behavior of a <xref:System.Windows.Controls.Button> is to enable an application to take some action when the user clicks it. By default, the <xref:System.Windows.Controls.Button> in WPF appears as a raised rectangle. While developing an application, you might want to take advantage of the behavior of a <xref:System.Windows.Controls.Button>--that is, by handling the button's click event--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>.
The following example creates a <xref:System.Windows.Controls.ControlTemplate> for a <xref:System.Windows.Controls.Button>. The <xref:System.Windows.Controls.ControlTemplate> creates a <xref:System.Windows.Controls.Button> with rounded corners and a gradient background. The <xref:System.Windows.Controls.ControlTemplate> contains a <xref:System.Windows.Controls.Border> whose <xref:System.Windows.Controls.Border.Background%2A> is a <xref:System.Windows.Media.LinearGradientBrush> with two <xref:System.Windows.Media.GradientStop> objects. The first <xref:System.Windows.Media.GradientStop> uses data binding to bind the <xref:System.Windows.Media.GradientStop.Color%2A> property of the <xref:System.Windows.Media.GradientStop> to the color of the button's background. When you set the <xref:System.Windows.Controls.Control.Background%2A> property of the <xref:System.Windows.Controls.Button>, the color of that value will be used as the first <xref:System.Windows.Media.GradientStop>. For more information about data binding, see [Data Binding Overview](../data/data-binding-overview.md). The example also creates a <xref:System.Windows.Trigger> that changes the appearance of the <xref:System.Windows.Controls.Button> when <xref:System.Windows.Controls.Primitives.ButtonBase.IsPressed%2A> is `true`.
@@ -66,7 +66,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
<a name="subscribing_to_events"></a>
## Subscribing to Events
You can subscribe to a control's event by using either [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or code, but you can only handle an event in code. The following example shows how to subscribe to the `Click` event of a <xref:System.Windows.Controls.Button>.
You can subscribe to a control's event by using either XAML or code, but you can only handle an event in code. The following example shows how to subscribe to the `Click` event of a <xref:System.Windows.Controls.Button>.
[!code-xaml[ControlsOverview#10](~/samples/snippets/csharp/VS_Snippets_Wpf/ControlsOverview/CSharp/Window1.xaml#10)]
@@ -80,7 +80,7 @@ ms.assetid: 3f255a8a-35a8-4712-9065-472ff7d75599
<a name="rich_content_in_controls"></a>
## Rich Content in Controls
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 [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
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.
- <xref:System.Windows.Controls.ContentControl>-- 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>.
@@ -10,7 +10,7 @@ ms.assetid: 241c1ce2-60f8-4613-a0ec-9b9bb25fb6af
---
# Label
<xref:System.Windows.Controls.Label> controls usually provide information in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. Historically, a <xref:System.Windows.Controls.Label> has contained only text, but because the <xref:System.Windows.Controls.Label> that ships with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is a <xref:System.Windows.Controls.ContentControl>, it can contain either text or a <xref:System.Windows.UIElement>.
<xref:System.Windows.Controls.Label> controls usually provide information in the user interface (UI). Historically, a <xref:System.Windows.Controls.Label> has contained only text, but because the <xref:System.Windows.Controls.Label> that ships with Windows Presentation Foundation (WPF) is a <xref:System.Windows.Controls.ContentControl>, it can contain either text or a <xref:System.Windows.UIElement>.
A <xref:System.Windows.Controls.Label> provides both functional and visual support for access keys. It is frequently used to enable quick keyboard access to controls such as a <xref:System.Windows.Controls.TextBox>. To assign a <xref:System.Windows.Controls.Label> to a <xref:System.Windows.Controls.Control>, set the <xref:System.Windows.Controls.Label.Target%2A?displayProperty=nameWithType> property to the control that should get focus when the user presses the access key.
@@ -22,7 +22,7 @@ The <xref:System.Windows.Controls.ListView> control provides the infrastructure
<a name="DefiningaListViewView"></a>
## Defining a View Mode for a ListView
To specify a view mode for the content of a <xref:System.Windows.Controls.ListView> control, you set the <xref:System.Windows.Controls.ListView.View%2A> property. One view mode that [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides is <xref:System.Windows.Controls.GridView>, which displays a collection of data items in a table that has customizable columns.
To specify a view mode for the content of a <xref:System.Windows.Controls.ListView> control, you set the <xref:System.Windows.Controls.ListView.View%2A> property. One view mode that Windows Presentation Foundation (WPF) provides is <xref:System.Windows.Controls.GridView>, which displays a collection of data items in a table that has customizable columns.
The following example shows how to define a <xref:System.Windows.Controls.GridView> for a <xref:System.Windows.Controls.ListView> control that displays employee information.
@@ -18,7 +18,7 @@ This example shows how to use the methods in the <xref:System.Windows.Controls.C
:::code language="xaml" source="snippets/manipulate-columns-and-rows-by-using-columndefinitionscollections/csharp/Window1.xaml" id="Snippet1":::
This example defines a series of custom methods, each corresponding to a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event in the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file. You can change the number of columns and rows in the <xref:System.Windows.Controls.Grid> in several ways, which includes adding or removing rows and columns; and counting the total number of rows and columns. To prevent <xref:System.ArgumentOutOfRangeException> and <xref:System.ArgumentException> exceptions, you can use the error-checking functionality that the <xref:System.Windows.Controls.ColumnDefinitionCollection.RemoveRange%2A> method provides.
This example defines a series of custom methods, each corresponding to a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event in the Extensible Application Markup Language (XAML) file. You can change the number of columns and rows in the <xref:System.Windows.Controls.Grid> in several ways, which includes adding or removing rows and columns; and counting the total number of rows and columns. To prevent <xref:System.ArgumentOutOfRangeException> and <xref:System.ArgumentException> exceptions, you can use the error-checking functionality that the <xref:System.Windows.Controls.ColumnDefinitionCollection.RemoveRange%2A> method provides.
:::code language="csharp" source="snippets/manipulate-columns-and-rows-by-using-columndefinitionscollections/csharp/Window1.xaml.cs" id="Snippet2":::
:::code language="vb" source="snippets/manipulate-columns-and-rows-by-using-columndefinitionscollections/vb/Window1.xaml.vb" id="Snippet2":::
@@ -10,7 +10,7 @@ helpviewer_keywords:
ms.assetid: 792943c5-335d-49dd-aa5b-ec1582a10088
---
# Panel
<xref:System.Windows.Controls.Panel> is the base class for all elements that support application layout in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
<xref:System.Windows.Controls.Panel> is the base class for all elements that support application layout in Windows Presentation Foundation (WPF).
## In This Section
[Panels Overview](panels-overview.md)
@@ -13,7 +13,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
---
# Panels Overview
<xref:System.Windows.Controls.Panel> elements are components that control the rendering of elements—their size and dimensions, their position, and the arrangement of their child content. The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a number of predefined <xref:System.Windows.Controls.Panel> elements as well as the ability to construct custom <xref:System.Windows.Controls.Panel> elements.
<xref:System.Windows.Controls.Panel> elements are components that control the rendering of elements—their size and dimensions, their position, and the arrangement of their child content. The Windows Presentation Foundation (WPF) provides a number of predefined <xref:System.Windows.Controls.Panel> elements as well as the ability to construct custom <xref:System.Windows.Controls.Panel> elements.
This topic contains the following sections.
@@ -35,9 +35,9 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
## The Panel Class
<xref:System.Windows.Controls.Panel> is the base class for all elements that provide layout support in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. Derived <xref:System.Windows.Controls.Panel> elements are used to position and arrange elements in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code.
<xref:System.Windows.Controls.Panel> is the base class for all elements that provide layout support in Windows Presentation Foundation (WPF). Derived <xref:System.Windows.Controls.Panel> elements are used to position and arrange elements in Extensible Application Markup Language (XAML) and code.
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes a comprehensive suite of derived panel implementations that enable many complex layouts. These derived classes expose properties and methods that enable most standard [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios. Developers who are unable to find a child arrangement behavior that meets their needs can create new layouts by overriding the <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> and <xref:System.Windows.FrameworkElement.MeasureOverride%2A> methods. For more information on custom layout behaviors, see [Custom Panel Elements](#Panels_custom_panel_elements).
The WPF includes a comprehensive suite of derived panel implementations that enable many complex layouts. These derived classes expose properties and methods that enable most standard user interface (UI) scenarios. Developers who are unable to find a child arrangement behavior that meets their needs can create new layouts by overriding the <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> and <xref:System.Windows.FrameworkElement.MeasureOverride%2A> methods. For more information on custom layout behaviors, see [Custom Panel Elements](#Panels_custom_panel_elements).
<a name="Panels_declared_members"></a>
@@ -53,15 +53,15 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
#### Attached Properties
Derived panel elements make extensive use of attached properties. An attached property is a specialized form of dependency property that does not have the conventional common language runtime (CLR) property "wrapper". Attached properties have a specialized syntax in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], which can be seen in several of the examples that follow.
Derived panel elements make extensive use of attached properties. An attached property is a specialized form of dependency property that does not have the conventional common language runtime (CLR) property "wrapper". Attached properties have a specialized syntax in Extensible Application Markup Language (XAML), which can be seen in several of the examples that follow.
One purpose of an attached property is to allow child elements to store unique values of a property that is actually defined by a parent element. An application of this functionality is having child elements inform the parent how they wish to be presented in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], which is extremely useful for application layout. For more information, see [Attached Properties Overview](../advanced/attached-properties-overview.md).
One purpose of an attached property is to allow child elements to store unique values of a property that is actually defined by a parent element. An application of this functionality is having child elements inform the parent how they wish to be presented in the user interface (UI), which is extremely useful for application layout. For more information, see [Attached Properties Overview](../advanced/attached-properties-overview.md).
<a name="Panels_derived_elements"></a>
## Derived Panel Elements
Many objects derive from <xref:System.Windows.Controls.Panel>, but not all of them are intended for use as root layout providers. There are six defined panel classes (<xref:System.Windows.Controls.Canvas>, <xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, <xref:System.Windows.Controls.StackPanel>, <xref:System.Windows.Controls.VirtualizingStackPanel>, and <xref:System.Windows.Controls.WrapPanel>) that are designed specifically for creating application [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)].
Many objects derive from <xref:System.Windows.Controls.Panel>, but not all of them are intended for use as root layout providers. There are six defined panel classes (<xref:System.Windows.Controls.Canvas>, <xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, <xref:System.Windows.Controls.StackPanel>, <xref:System.Windows.Controls.VirtualizingStackPanel>, and <xref:System.Windows.Controls.WrapPanel>) that are designed specifically for creating application UI.
Each panel element encapsulates its own special functionality, as seen in the following table.
@@ -82,7 +82,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
## User Interface Panels
There are six panel classes available in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] that are optimized to support [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios: <xref:System.Windows.Controls.Canvas>, <xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, <xref:System.Windows.Controls.StackPanel>, <xref:System.Windows.Controls.VirtualizingStackPanel>, and <xref:System.Windows.Controls.WrapPanel>. These panel elements are easy to use, versatile, and extensible enough for most applications.
There are six panel classes available in UI scenarios: <xref:System.Windows.Controls.Canvas>, <xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, <xref:System.Windows.Controls.StackPanel>, <xref:System.Windows.Controls.VirtualizingStackPanel>, and <xref:System.Windows.Controls.WrapPanel>. These panel elements are easy to use, versatile, and extensible enough for most applications.
Each derived <xref:System.Windows.Controls.Panel> element treats sizing constraints differently. Understanding how a <xref:System.Windows.Controls.Panel> handles constraints in either the horizontal or vertical direction can make layout more predictable.
@@ -113,13 +113,13 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
#### Defining and Using a Canvas
A <xref:System.Windows.Controls.Canvas> can be instantiated simply by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] or code. The following example demonstrates how to use <xref:System.Windows.Controls.Canvas> to absolutely position content. This code produces three 100-pixel squares. The first square is red, and its top-left (*x, y*) position is specified as (0, 0). The second square is green, and its top-left position is (100, 100), just below and to the right of the first square. The third square is blue, and its top-left position is (50, 50), thus encompassing the lower-right quadrant of the first square and the upper-left quadrant of the second. Because the third square is laid out last, it appears to be on top of the other two squares—that is, the overlapping portions assume the color of the third box.
A <xref:System.Windows.Controls.Canvas> can be instantiated simply by using Extensible Application Markup Language (XAML) or code. The following example demonstrates how to use <xref:System.Windows.Controls.Canvas> to absolutely position content. This code produces three 100-pixel squares. The first square is red, and its top-left (*x, y*) position is specified as (0, 0). The second square is green, and its top-left position is (100, 100), just below and to the right of the first square. The third square is blue, and its top-left position is (50, 50), thus encompassing the lower-right quadrant of the first square and the upper-left quadrant of the second. Because the third square is laid out last, it appears to be on top of the other two squares—that is, the overlapping portions assume the color of the third box.
[!code-csharp[CanvasOvwSample#1](~/samples/snippets/csharp/VS_Snippets_Wpf/CanvasOvwSample/CSharp/Canvas_Ovw_Sample.cs#1)]
[!code-vb[CanvasOvwSample#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CanvasOvwSample/VisualBasic/canvas_vb.vb#1)]
[!code-xaml[CanvasOvwSample#1](~/samples/snippets/xaml/VS_Snippets_Wpf/CanvasOvwSample/XAML/default.xaml#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A typical Canvas Element.](./media/panel-intro-canvas.PNG "panel_intro_canvas")
@@ -129,7 +129,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
The <xref:System.Windows.Controls.DockPanel> element uses the <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> attached property as set in child content elements to position content along the edges of a container. When <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> is set to <xref:System.Windows.Controls.Dock.Top> or <xref:System.Windows.Controls.Dock.Bottom>, it positions child elements above or below each other. When <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> is set to <xref:System.Windows.Controls.Dock.Left> or <xref:System.Windows.Controls.Dock.Right>, it positions child elements to the left or right of each other. The <xref:System.Windows.Controls.DockPanel.LastChildFill%2A> property determines the position of the final element added as a child of a <xref:System.Windows.Controls.DockPanel>.
You can use <xref:System.Windows.Controls.DockPanel> to position a group of related controls, such as a set of buttons. Alternately, you can use it to create a "paned" [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], similar to that found in Microsoft Outlook.
You can use <xref:System.Windows.Controls.DockPanel> to position a group of related controls, such as a set of buttons. Alternately, you can use it to create a "paned" UI, similar to that found in Microsoft Outlook.
#### Sizing to Content
@@ -148,7 +148,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
[!code-vb[DockPanelOvwSample#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DockPanelOvwSample/VisualBasic/dockpanel_vb.vb#1)]
[!code-xaml[DockPanelOvwSample#1](~/samples/snippets/xaml/VS_Snippets_Wpf/DockPanelOvwSample/XAML/default.xaml#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A typical DockPanel scenario.](./media/panel-intro-dockpanel.PNG "panel_intro_dockpanel")
@@ -164,16 +164,16 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
#### Sizing Behavior of Columns and Rows
Columns and rows defined within a <xref:System.Windows.Controls.Grid> can take advantage of <xref:System.Windows.GridUnitType.Star> sizing in order to distribute remaining space proportionally. When <xref:System.Windows.GridUnitType.Star> is selected as the Height or Width of a row or column, that column or row receives a weighted proportion of remaining available space. This is in contrast to <xref:System.Windows.GridUnitType.Auto>, which will distribute space evenly based on the size of the content within a column or row. This value is expressed as `*` or `2*` when using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. In the first case, the row or column would receive one times the available space, in the second case, two times, and so on. By combining this technique to proportionally distribute space with a <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A> and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> value of `Stretch` it is possible to partition layout space by percentage of screen space. <xref:System.Windows.Controls.Grid> is the only layout panel that can distribute space in this manner.
Columns and rows defined within a <xref:System.Windows.Controls.Grid> can take advantage of <xref:System.Windows.GridUnitType.Star> sizing in order to distribute remaining space proportionally. When <xref:System.Windows.GridUnitType.Star> is selected as the Height or Width of a row or column, that column or row receives a weighted proportion of remaining available space. This is in contrast to <xref:System.Windows.GridUnitType.Auto>, which will distribute space evenly based on the size of the content within a column or row. This value is expressed as `*` or `2*` when using Extensible Application Markup Language (XAML). In the first case, the row or column would receive one times the available space, in the second case, two times, and so on. By combining this technique to proportionally distribute space with a <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A> and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> value of `Stretch` it is possible to partition layout space by percentage of screen space. <xref:System.Windows.Controls.Grid> is the only layout panel that can distribute space in this manner.
#### Defining and Using a Grid
The following example demonstrates how to build a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] similar to that found on the Run dialog available on the Windows Start menu.
The following example demonstrates how to build a UI similar to that found on the Run dialog available on the Windows Start menu.
[!code-csharp[GridRunDialog#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GridRunDialog/CSharp/window1.xaml.cs#1)]
[!code-vb[GridRunDialog#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/GridRunDialog/VisualBasic/grid_vb.vb#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A typical Grid Element.](./media/avalon-run-dialog.PNG "avalon_run_dialog")
@@ -205,7 +205,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
[!code-csharp[StackPanel_ovw2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/StackPanel_ovw2/CSharp/StackPanel_Ovw_Sample2.cs#1)]
[!code-vb[StackPanel_ovw2#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/StackPanel_ovw2/VisualBasic/StackPanelOvw.vb#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A typical StackPanel element.](./media/panel-intro-stackpanel.PNG "panel_intro_stackpanel")
@@ -213,7 +213,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
#### VirtualizingStackPanel
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides a variation of the <xref:System.Windows.Controls.StackPanel> element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of elements are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. <xref:System.Windows.Controls.VirtualizingStackPanel> (through functionality provided by <xref:System.Windows.Controls.VirtualizingPanel>) calculates visible items and works with the <xref:System.Windows.Controls.ItemContainerGenerator> from an <xref:System.Windows.Controls.ItemsControl> (such as <xref:System.Windows.Controls.ListBox> or <xref:System.Windows.Controls.ListView>) to only create elements for visible items.
WPF also provides a variation of the <xref:System.Windows.Controls.StackPanel> element that automatically "virtualizes" data-bound child content. In this context, the word virtualize refers to a technique by which a subset of elements are generated from a larger number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and processor, to generate a large number of UI elements when only a few may be on the screen at a given time. <xref:System.Windows.Controls.VirtualizingStackPanel> (through functionality provided by <xref:System.Windows.Controls.VirtualizingPanel>) calculates visible items and works with the <xref:System.Windows.Controls.ItemContainerGenerator> from an <xref:System.Windows.Controls.ItemsControl> (such as <xref:System.Windows.Controls.ListBox> or <xref:System.Windows.Controls.ListView>) to only create elements for visible items.
The <xref:System.Windows.Controls.VirtualizingStackPanel> element is automatically set as the items host for controls such as the <xref:System.Windows.Controls.ListBox>. When hosting a data bound collection, content is automatically virtualized, as long as the content is within the bounds of a <xref:System.Windows.Controls.ScrollViewer>. This greatly improves performance when hosting many child items.
@@ -225,7 +225,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
### WrapPanel
<xref:System.Windows.Controls.WrapPanel> is used to position child elements in sequential position from left to right, breaking content to the next line when it reaches the edge of its parent container. Content can be oriented horizontally or vertically. <xref:System.Windows.Controls.WrapPanel> is useful for simple flowing [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios. It can also be used to apply uniform sizing to all of its child elements.
<xref:System.Windows.Controls.WrapPanel> is used to position child elements in sequential position from left to right, breaking content to the next line when it reaches the edge of its parent container. Content can be oriented horizontally or vertically. <xref:System.Windows.Controls.WrapPanel> is useful for simple flowing user interface (UI) scenarios. It can also be used to apply uniform sizing to all of its child elements.
The following example demonstrates how to create a <xref:System.Windows.Controls.WrapPanel> to display <xref:System.Windows.Controls.Button> controls that wrap when they reach the edge of their container.
@@ -234,7 +234,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
[!code-vb[WrapPanel_Intro#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WrapPanel_Intro/VisualBasic/WrapPanel_vb.vb#1)]
[!code-xaml[WrapPanel_Intro#1](~/samples/snippets/xaml/VS_Snippets_Wpf/WrapPanel_Intro/XAML/default.xaml#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A typical WrapPanel Element.](./media/wrappanel-element.PNG "WrapPanel_Element")
@@ -242,16 +242,16 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
## Nested Panel Elements
<xref:System.Windows.Controls.Panel> elements can be nested within each other in order to produce complex layouts. This can prove very useful in situations where one <xref:System.Windows.Controls.Panel> is ideal for a portion of a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], but may not meet the needs of a different portion of the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)].
<xref:System.Windows.Controls.Panel> elements can be nested within each other in order to produce complex layouts. This can prove very useful in situations where one <xref:System.Windows.Controls.Panel> is ideal for a portion of a UI, but may not meet the needs of a different portion of the UI.
There is no practical limit to the amount of nesting that your application can support, however, it is generally best to limit your application to only use those panels that are actually necessary for your desired layout. In many cases, a <xref:System.Windows.Controls.Grid> element can be used instead of nested panels due to its flexibility as a layout container. This can increase performance in your application by keeping unnecessary elements out of the tree.
The following example demonstrates how to create a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that takes advantage of nested <xref:System.Windows.Controls.Panel> elements in order to achieve a specific layout. In this particular case, a <xref:System.Windows.Controls.DockPanel> element is used to provide [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] structure, and nested <xref:System.Windows.Controls.StackPanel> elements, a <xref:System.Windows.Controls.Grid>, and a <xref:System.Windows.Controls.Canvas> are used to position child elements precisely within the parent <xref:System.Windows.Controls.DockPanel>.
The following example demonstrates how to create a UI that takes advantage of nested <xref:System.Windows.Controls.Panel> elements in order to achieve a specific layout. In this particular case, a <xref:System.Windows.Controls.DockPanel> element is used to provide UI structure, and nested <xref:System.Windows.Controls.StackPanel> elements, a <xref:System.Windows.Controls.Grid>, and a <xref:System.Windows.Controls.Canvas> are used to position child elements precisely within the parent <xref:System.Windows.Controls.DockPanel>.
[!code-csharp[Nested_Panels#1](~/samples/snippets/csharp/VS_Snippets_Wpf/Nested_Panels/CSharp/nestedpanels.cs#1)]
[!code-vb[Nested_Panels#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/Nested_Panels/VisualBasic/nestedpanels.vb#1)]
The compiled application yields a new [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like this.
The compiled application yields a new UI that looks like this.
![A UI that takes advantage of nested panels.](./media/nested-panels.PNG "nested_panels")
@@ -259,7 +259,7 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
## Custom Panel Elements
While [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides an array of flexible layout controls, custom layout behaviors can also be achieved by overriding the <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> and <xref:System.Windows.FrameworkElement.MeasureOverride%2A> methods. Custom sizing and positioning can be accomplished by defining new positioning behaviors within these override methods.
While WPF provides an array of flexible layout controls, custom layout behaviors can also be achieved by overriding the <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> and <xref:System.Windows.FrameworkElement.MeasureOverride%2A> methods. Custom sizing and positioning can be accomplished by defining new positioning behaviors within these override methods.
Similarly, custom layout behaviors based on derived classes (such as <xref:System.Windows.Controls.Canvas> or <xref:System.Windows.Controls.Grid>) can be defined by overriding their <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> and <xref:System.Windows.FrameworkElement.MeasureOverride%2A> methods.
@@ -275,15 +275,15 @@ ms.assetid: f73644af-9941-4611-8754-6d4cef03fc44
## Localization/Globalization Support
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports a number of features that assist in the creation of localizable [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)].
UI.
All panel elements natively support the <xref:System.Windows.FrameworkElement.FlowDirection%2A> property, which can be used to dynamically re-flow content based on a user's locale or language settings. For more information, see <xref:System.Windows.FrameworkElement.FlowDirection%2A>.
The <xref:System.Windows.Window.SizeToContent%2A> property provides a mechanism that enables application developers to anticipate the needs of localized [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. Using the <xref:System.Windows.SizeToContent.WidthAndHeight> value of this property, a parent <xref:System.Windows.Window> always sizes dynamically to fit content and is not constrained by artificial height or width restrictions.
The <xref:System.Windows.Window.SizeToContent%2A> property provides a mechanism that enables application developers to anticipate the needs of localized UI. Using the <xref:System.Windows.SizeToContent.WidthAndHeight> value of this property, a parent <xref:System.Windows.Window> always sizes dynamically to fit content and is not constrained by artificial height or width restrictions.
<xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, and <xref:System.Windows.Controls.StackPanel> are all good choices for localizable [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. <xref:System.Windows.Controls.Canvas> is not a good choice, however, because it positions content absolutely, making it difficult to localize.
<xref:System.Windows.Controls.DockPanel>, <xref:System.Windows.Controls.Grid>, and <xref:System.Windows.Controls.StackPanel> are all good choices for localizable UI. <xref:System.Windows.Controls.Canvas> is not a good choice, however, because it positions content absolutely, making it difficult to localize.
For additional information on creating [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications with localizable user interfaces (UIs)s, see the [Use Automatic Layout Overview](../advanced/use-automatic-layout-overview.md).
For additional information on creating WPF applications with localizable user interfaces (UIs)s, see the [Use Automatic Layout Overview](../advanced/use-automatic-layout-overview.md).
## See also
@@ -16,7 +16,7 @@ ms.assetid: c771a0b8-c6b4-4240-aecd-a21d0ba51a2e
This example shows how to position the cursor at the beginning or end of the text contents of a <xref:System.Windows.Controls.TextBox> control.
## Define a TextBox control
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] code describes a <xref:System.Windows.Controls.TextBox> control and assigns it a Name.
The following Extensible Application Markup Language (XAML) code describes a <xref:System.Windows.Controls.TextBox> control and assigns it a Name.
[!code-xaml[TextBox_MiscCode#_MoveCursorXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_movecursorxaml)]
@@ -12,7 +12,7 @@ ms.assetid: c94548b2-c1e9-4b62-b10c-dd8740eb23d8
---
# RichTextBox Overview
The <xref:System.Windows.Controls.RichTextBox> control enables you to display or edit flow content including paragraphs, images, tables, and more. This topic introduces the <xref:System.Windows.Controls.TextBox> class and provides examples of how to use it in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and C#.
The <xref:System.Windows.Controls.RichTextBox> control enables you to display or edit flow content including paragraphs, images, tables, and more. This topic introduces the <xref:System.Windows.Controls.TextBox> class and provides examples of how to use it in both Extensible Application Markup Language (XAML) and C#.
<a name="textbox_or_richtextbox"></a>
@@ -13,13 +13,13 @@ ms.assetid: 94a13b94-cfdf-4b12-a1aa-90cb50c6e9b9
---
# ScrollViewer Overview
Content within a user interface is often larger than a computer screen's display area. The <xref:System.Windows.Controls.ScrollViewer> control provides a convenient way to enable scrolling of content in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. This topic introduces the <xref:System.Windows.Controls.ScrollViewer> element and provides several usage examples.
Content within a user interface is often larger than a computer screen's display area. The <xref:System.Windows.Controls.ScrollViewer> control provides a convenient way to enable scrolling of content in Windows Presentation Foundation (WPF) applications. This topic introduces the <xref:System.Windows.Controls.ScrollViewer> element and provides several usage examples.
<a name="what_is_a_scrollviewer_element"></a>
## The ScrollViewer Control
There are two predefined elements that enable scrolling in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications: <xref:System.Windows.Controls.Primitives.ScrollBar> and <xref:System.Windows.Controls.ScrollViewer>. The <xref:System.Windows.Controls.ScrollViewer> control encapsulates horizontal and vertical <xref:System.Windows.Controls.Primitives.ScrollBar> elements and a content container (such as a <xref:System.Windows.Controls.Panel> element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the <xref:System.Windows.Controls.Primitives.ScrollBar> element for content scrolling. However, you can use the <xref:System.Windows.Controls.ScrollViewer> element by itself because it is a composite control that encapsulates <xref:System.Windows.Controls.Primitives.ScrollBar> functionality.
There are two predefined elements that enable scrolling in WPF applications: <xref:System.Windows.Controls.Primitives.ScrollBar> and <xref:System.Windows.Controls.ScrollViewer>. The <xref:System.Windows.Controls.ScrollViewer> control encapsulates horizontal and vertical <xref:System.Windows.Controls.Primitives.ScrollBar> elements and a content container (such as a <xref:System.Windows.Controls.Panel> element) in order to display other visible elements in a scrollable area. You must build a custom object in order to use the <xref:System.Windows.Controls.Primitives.ScrollBar> element for content scrolling. However, you can use the <xref:System.Windows.Controls.ScrollViewer> element by itself because it is a composite control that encapsulates <xref:System.Windows.Controls.Primitives.ScrollBar> functionality.
The <xref:System.Windows.Controls.ScrollViewer> control responds to both mouse and keyboard commands, and defines numerous methods with which to scroll content by predetermined increments. You can use the <xref:System.Windows.Controls.ScrollViewer.ScrollChanged> event to detect a change in a <xref:System.Windows.Controls.ScrollViewer> state.
@@ -29,7 +29,7 @@ Content within a user interface is often larger than a computer screen's display
## Physical vs. Logical Scrolling
Physical scrolling is used to scroll content by a predetermined physical increment, typically by a value that is declared in pixels. Logical scrolling is used to scroll to the next item in the logical tree. Physical scrolling is the default scroll behavior for most <xref:System.Windows.Controls.Panel> elements. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports both types of scrolling.
Physical scrolling is used to scroll content by a predetermined physical increment, typically by a value that is declared in pixels. Logical scrolling is used to scroll to the next item in the logical tree. Physical scrolling is the default scroll behavior for most <xref:System.Windows.Controls.Panel> elements. WPF supports both types of scrolling.
#### The IScrollInfo Interface
@@ -10,9 +10,9 @@ helpviewer_keywords:
ms.assetid: 24720bca-341a-4b03-8a6b-7a678023b10a
---
# TextBlock Overview
The <xref:System.Windows.Controls.TextBlock> control provides flexible text support for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. The element is targeted primarily toward basic [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios that do not require more than one paragraph of text. It supports a number of properties that enable precise control of presentation, such as <xref:System.Windows.Controls.TextBlock.FontFamily%2A>, <xref:System.Windows.Controls.TextBlock.FontSize%2A>, <xref:System.Windows.Controls.TextBlock.FontWeight%2A>, <xref:System.Windows.Controls.TextBlock.TextEffects%2A>, and <xref:System.Windows.Controls.TextBlock.TextWrapping%2A>. Text content can be added using the <xref:System.Windows.Controls.TextBlock.Text%2A> property. When used in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], content between the open and closing tag is implicitly added as the text of the element.
The <xref:System.Windows.Controls.TextBlock> control provides flexible text support for UI scenarios that do not require more than one paragraph of text. It supports a number of properties that enable precise control of presentation, such as <xref:System.Windows.Controls.TextBlock.FontFamily%2A>, <xref:System.Windows.Controls.TextBlock.FontSize%2A>, <xref:System.Windows.Controls.TextBlock.FontWeight%2A>, <xref:System.Windows.Controls.TextBlock.TextEffects%2A>, and <xref:System.Windows.Controls.TextBlock.TextWrapping%2A>. Text content can be added using the <xref:System.Windows.Controls.TextBlock.Text%2A> property. When used in XAML, content between the open and closing tag is implicitly added as the text of the element.
A <xref:System.Windows.Controls.TextBlock> element can be instantiated very simply using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
A <xref:System.Windows.Controls.TextBlock> element can be instantiated very simply using XAML.
[!code-xaml[TextBlockSnip_XAML#2](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBlockSnip_XAML/CS/default.xaml#2)]
@@ -9,7 +9,7 @@ helpviewer_keywords:
ms.assetid: ea5f7826-7a92-4de9-9eee-10ef700ce7b6
---
# TextBlock
The <xref:System.Windows.Controls.TextBlock> control provides flexible text support for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. The element is targeted primarily toward basic [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios that do not require more than one paragraph of text.
The <xref:System.Windows.Controls.TextBlock> control provides flexible text support for UI scenarios that do not require more than one paragraph of text.
## In This Section
[TextBlock Overview](textblock-overview.md)
@@ -7,7 +7,7 @@ helpviewer_keywords:
ms.assetid: 1ba6dc5b-11a7-4247-9213-36c6729ee35f
---
# TextBox Overview
The <xref:System.Windows.Controls.TextBox> class enables you to display or edit unformatted text. A common use of a <xref:System.Windows.Controls.TextBox> is editing unformatted text in a form. For example, a form asking for the user's name, phone number, etc would use <xref:System.Windows.Controls.TextBox> controls for text input. This topic introduces the <xref:System.Windows.Controls.TextBox> class and provides examples of how to use it in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and C#.
The <xref:System.Windows.Controls.TextBox> class enables you to display or edit unformatted text. A common use of a <xref:System.Windows.Controls.TextBox> is editing unformatted text in a form. For example, a form asking for the user's name, phone number, etc would use <xref:System.Windows.Controls.TextBox> controls for text input. This topic introduces the <xref:System.Windows.Controls.TextBox> class and provides examples of how to use it in both Extensible Application Markup Language (XAML) and C#.
<a name="textbox_or_richtextbox"></a>
## TextBox or RichTextBox?
@@ -43,7 +43,7 @@ The <xref:System.Windows.Controls.TextBox> class enables you to display or edit
[!code-xaml[TextBoxMiscSnippets_snip#BasicTextBoxExampleWholePage](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBoxMiscSnippets_snip/csharp/basictextboxexample.xaml#basictextboxexamplewholepage)]
You can also create a <xref:System.Windows.Controls.TextBox> that allows the user to enter multiple lines of text. For example, if your form asked for a biographical sketch of the user, you would want to use a <xref:System.Windows.Controls.TextBox> that supports multiple lines of text. The following example shows how to use [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] to define a <xref:System.Windows.Controls.TextBox> control that automatically expands to accommodate multiple lines of text.
You can also create a <xref:System.Windows.Controls.TextBox> that allows the user to enter multiple lines of text. For example, if your form asked for a biographical sketch of the user, you would want to use a <xref:System.Windows.Controls.TextBox> that supports multiple lines of text. The following example shows how to use Extensible Application Markup Language (XAML) to define a <xref:System.Windows.Controls.TextBox> control that automatically expands to accommodate multiple lines of text.
[!code-xaml[TextBox_MiscCode#_MultilineTextBoxXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TextBox_MiscCode/CSharp/Window1.xaml#_multilinetextboxxaml)]
@@ -11,7 +11,7 @@ ms.assetid: a8edb32c-118d-4f31-b6e6-8899082b504b
<a name="ToolBarControl"></a>
## ToolBar Control
The <xref:System.Windows.Controls.ToolBar> control takes its name from the bar-like arrangement of buttons or other controls into a single row or column. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] <xref:System.Windows.Controls.ToolBar> controls provide an overflow mechanism which places any items that do not fit naturally within a size-constrained <xref:System.Windows.Controls.ToolBar> into a special overflow area. Also, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] <xref:System.Windows.Controls.ToolBar> controls are usually used with the related <xref:System.Windows.Controls.ToolBarTray> control, which provides special layout behavior as well as support for user-initiated sizing and arranging of toolbars.
The <xref:System.Windows.Controls.ToolBar> control takes its name from the bar-like arrangement of buttons or other controls into a single row or column. WPF <xref:System.Windows.Controls.ToolBar> controls provide an overflow mechanism which places any items that do not fit naturally within a size-constrained <xref:System.Windows.Controls.ToolBar> into a special overflow area. Also, WPF <xref:System.Windows.Controls.ToolBar> controls are usually used with the related <xref:System.Windows.Controls.ToolBarTray> control, which provides special layout behavior as well as support for user-initiated sizing and arranging of toolbars.
<a name="Creating_ToolBars"></a>
## Specifying the Position of ToolBars in a ToolBarTray
@@ -35,7 +35,7 @@ A tooltip is a small pop-up window that appears when a user pauses the mouse poi
[!code-xaml[GroupBoxSnippet#ToolTipString](~/samples/snippets/csharp/VS_Snippets_Wpf/GroupBoxSnippet/CS/Window1.xaml#tooltipstring)]
You can also define a tooltip as a <xref:System.Windows.Controls.ToolTip> object. The following example uses [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to specify a <xref:System.Windows.Controls.ToolTip> object as the tooltip of a <xref:System.Windows.Controls.TextBox> element. Note that the example specifies the <xref:System.Windows.Controls.ToolTip> by setting the <xref:System.Windows.FrameworkElement.ToolTip%2A?displayProperty=nameWithType> property.
You can also define a tooltip as a <xref:System.Windows.Controls.ToolTip> object. The following example uses XAML to specify a <xref:System.Windows.Controls.ToolTip> object as the tooltip of a <xref:System.Windows.Controls.TextBox> element. Note that the example specifies the <xref:System.Windows.Controls.ToolTip> by setting the <xref:System.Windows.FrameworkElement.ToolTip%2A?displayProperty=nameWithType> property.
[!code-xaml[ToolTipSimple#ToolTip](~/samples/snippets/csharp/VS_Snippets_Wpf/ToolTipSimple/CSharp/Pane1.xaml#tooltip)]
@@ -21,7 +21,7 @@ The <xref:System.Windows.Controls.TreeView> control provides a way to display in
## Creating a TreeView
The <xref:System.Windows.Controls.TreeView> control contains a hierarchy of <xref:System.Windows.Controls.TreeViewItem> controls. A <xref:System.Windows.Controls.TreeViewItem> control is a <xref:System.Windows.Controls.HeaderedItemsControl> that has a <xref:System.Windows.Controls.HeaderedItemsControl.Header%2A> and an <xref:System.Windows.Controls.ItemsControl.Items%2A> collection.
If you are defining a <xref:System.Windows.Controls.TreeView> by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], you can explicitly define the <xref:System.Windows.Controls.HeaderedItemsControl.Header%2A> content of a <xref:System.Windows.Controls.TreeViewItem> control and the items that make up its collection. The previous illustration demonstrates this method.
If you are defining a <xref:System.Windows.Controls.TreeView> by using Extensible Application Markup Language (XAML), you can explicitly define the <xref:System.Windows.Controls.HeaderedItemsControl.Header%2A> content of a <xref:System.Windows.Controls.TreeViewItem> control and the items that make up its collection. The previous illustration demonstrates this method.
You can also specify an <xref:System.Windows.Controls.ItemsControl.ItemsSource%2A> as a data source and then specify a <xref:System.Windows.Controls.HeaderedItemsControl.HeaderTemplate%2A> and <xref:System.Windows.Controls.ItemsControl.ItemTemplate%2A> to define the <xref:System.Windows.Controls.TreeViewItem> content.
@@ -13,13 +13,13 @@ helpviewer_keywords:
ms.assetid: 47b310fc-fbd5-4ce2-a606-22d04c6d4911
---
# UI Automation of a WPF Custom Control
[!INCLUDE[TLA#tla_uiautomation](../../../includes/tlasharptla-uiautomation-md.md)] provides a single, generalized interface that automation clients can use to examine or operate the user interfaces of a variety of platforms and frameworks. [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] enables both quality-assurance (test) code and accessibility applications such as screen readers to examine user-interface elements and simulate user interaction with them from other code. For information about [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] across all platforms, see Accessibility.
UI Automation enables both quality-assurance (test) code and accessibility applications such as screen readers to examine user-interface elements and simulate user interaction with them from other code. For information about UI Automation across all platforms, see Accessibility.
This topic describes how to implement a server-side UI Automation provider for a custom control that runs in a WPF application. WPF supports [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] through a tree of peer automation objects that parallels the tree of user interface elements. Test code and applications that provide accessibility features can use automation peer objects directly (for in-process code) or through the generalized interface provided by [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)].
This topic describes how to implement a server-side UI Automation provider for a custom control that runs in a WPF application. WPF supports UI Automation through a tree of peer automation objects that parallels the tree of user interface elements. Test code and applications that provide accessibility features can use automation peer objects directly (for in-process code) or through the generalized interface provided by UI Automation.
<a name="AutomationPeerClasses"></a>
## Automation Peer Classes
WPF controls support [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] through a tree of peer classes that derive from <xref:System.Windows.Automation.Peers.AutomationPeer>. By convention, peer class names begin with the control class name and end with "AutomationPeer". For example, <xref:System.Windows.Automation.Peers.ButtonAutomationPeer> is the peer class for the <xref:System.Windows.Controls.Button> control class. The peer classes are roughly equivalent to [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] control types but are specific to WPF elements. Automation code that accesses WPF applications through the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] interface does not use automation peers directly, but automation code in the same process space can use automation peers directly.
WPF controls support UI Automation through a tree of peer classes that derive from <xref:System.Windows.Automation.Peers.AutomationPeer>. By convention, peer class names begin with the control class name and end with "AutomationPeer". For example, <xref:System.Windows.Automation.Peers.ButtonAutomationPeer> is the peer class for the <xref:System.Windows.Controls.Button> control class. The peer classes are roughly equivalent to UI Automation control types but are specific to WPF elements. Automation code that accesses WPF applications through the UI Automation interface does not use automation peers directly, but automation code in the same process space can use automation peers directly.
<a name="BuiltInAutomationPeerClasses"></a>
## Built-in Automation Peer Classes
@@ -45,7 +45,7 @@ ms.assetid: 47b310fc-fbd5-4ce2-a606-22d04c6d4911
Override the <xref:System.Windows.UIElement.OnCreateAutomationPeer%2A> method for your custom control so that it returns your provider object, which must derive directly or indirectly from <xref:System.Windows.Automation.Peers.AutomationPeer>.
### Override GetPattern
Automation peers simplify some implementation aspects of server-side [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the <xref:System.Windows.Automation.Provider?displayProperty=nameWithType> namespace, such as <xref:System.Windows.Automation.Provider.IInvokeProvider>. The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> returns the object that supports the specified pattern. [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] code calls the <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> method and specifies a <xref:System.Windows.Automation.Peers.PatternInterface> enumeration value. Your override of <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] peer would implement the <xref:System.Windows.Automation.Provider.IRangeValueProvider> interface. The following example shows how the peer's <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> method is overridden to respond to a <xref:System.Windows.Automation.Peers.PatternInterface.RangeValue?displayProperty=nameWithType> value.
Automation peers simplify some implementation aspects of server-side UI Automation providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the <xref:System.Windows.Automation.Provider?displayProperty=nameWithType> namespace, such as <xref:System.Windows.Automation.Provider.IInvokeProvider>. The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> returns the object that supports the specified pattern. UI Automation code calls the <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> method and specifies a <xref:System.Windows.Automation.Peers.PatternInterface> enumeration value. Your override of <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its UI Automation peer would implement the <xref:System.Windows.Automation.Provider.IRangeValueProvider> interface. The following example shows how the peer's <xref:System.Windows.Automation.Peers.UIElementAutomationPeer.GetPattern%2A> method is overridden to respond to a <xref:System.Windows.Automation.Peers.PatternInterface.RangeValue?displayProperty=nameWithType> value.
[!code-csharp[CustomControlNumericUpDown#GetPattern](~/samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#getpattern)]
[!code-vb[CustomControlNumericUpDown#GetPattern](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#getpattern)]
@@ -102,11 +102,11 @@ End Class
[!code-csharp[CustomControlNumericUpDown#CoreOverrides](~/samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#coreoverrides)]
[!code-vb[CustomControlNumericUpDown#CoreOverrides](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#coreoverrides)]
Your implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetAutomationControlTypeCore%2A> describes your control by returning a <xref:System.Windows.Automation.ControlType> value. Although you can return <xref:System.Windows.Automation.ControlType.Custom?displayProperty=nameWithType>, you should return one of the more specific control types if it accurately describes your control. A return value of <xref:System.Windows.Automation.ControlType.Custom?displayProperty=nameWithType> requires extra work for the provider to implement [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)], and [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns.
Your implementation of <xref:System.Windows.Automation.Peers.AutomationPeer.GetAutomationControlTypeCore%2A> describes your control by returning a <xref:System.Windows.Automation.ControlType> value. Although you can return <xref:System.Windows.Automation.ControlType.Custom?displayProperty=nameWithType>, you should return one of the more specific control types if it accurately describes your control. A return value of <xref:System.Windows.Automation.ControlType.Custom?displayProperty=nameWithType> requires extra work for the provider to implement UI Automation, and UI Automation client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns.
Implement the <xref:System.Windows.Automation.Peers.AutomationPeer.IsContentElementCore%2A> and <xref:System.Windows.Automation.Peers.AutomationPeer.IsControlElementCore%2A> methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). By default, both methods return `true`. These settings improve the usability of automation tools such as screen readers, which may use these methods to filter the automation tree. If your <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> method transfers pattern handling to a subelement peer, the subelement peer's <xref:System.Windows.Automation.Peers.AutomationPeer.IsControlElementCore%2A> method can return false to hide the subelement peer from the automation tree. For example, scrolling in a <xref:System.Windows.Controls.ListBox> is handled by a <xref:System.Windows.Controls.ScrollViewer>, and the automation peer for <xref:System.Windows.Automation.Peers.PatternInterface.Scroll?displayProperty=nameWithType> is returned by the <xref:System.Windows.Automation.Peers.AutomationPeer.GetPattern%2A> method of the <xref:System.Windows.Automation.Peers.ScrollViewerAutomationPeer> that is associated with the <xref:System.Windows.Automation.Peers.ListBoxAutomationPeer>.Therefore, the <xref:System.Windows.Automation.Peers.AutomationPeer.IsControlElementCore%2A> method of the <xref:System.Windows.Automation.Peers.ScrollViewerAutomationPeer> returns `false`, so that the <xref:System.Windows.Automation.Peers.ScrollViewerAutomationPeer> does not appear in the automation tree.
Your automation peer should provide appropriate default values for your control. Note that XAML that references your control can override your peer implementations of core methods by including <xref:System.Windows.Automation.AutomationProperties> attributes. For example, the following XAML creates a button that has two customized [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties.
Your automation peer should provide appropriate default values for your control. Note that XAML that references your control can override your peer implementations of core methods by including <xref:System.Windows.Automation.AutomationProperties> attributes. For example, the following XAML creates a button that has two customized UI Automation properties.
```xaml
<Button AutomationProperties.Name="Special"
@@ -12,7 +12,7 @@ ms.assetid: ff5037c2-bba7-4cae-8abb-6475b686c48e
This walkthrough steps you through the process of creating a WPF customized button using Microsoft Expression Blend.
> [!IMPORTANT]
> Microsoft Expression Blend works by generating [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] that is then compiled to make the executable program. If you would rather work with XAML directly, there is another walkthrough that creates the same application as this one using XAML with Visual Studio rather than Blend. See [Create a Button by Using XAML](walkthrough-create-a-button-by-using-xaml.md) for more information.
> Microsoft Expression Blend works by generating Extensible Application Markup Language (XAML) that is then compiled to make the executable program. If you would rather work with XAML directly, there is another walkthrough that creates the same application as this one using XAML with Visual Studio rather than Blend. See [Create a Button by Using XAML](walkthrough-create-a-button-by-using-xaml.md) for more information.
The following illustration shows the customized button that you will create.
@@ -8,10 +8,10 @@ ms.assetid: 138c41c4-1759-4bbf-8d77-77031a06a8a0
---
# Walkthrough: Create a Button by Using XAML
The objective of this walkthrough is to learn how to create an animated button for use in a Windows Presentation Foundation (WPF) application. This walkthrough uses styles and a template to create a customized button resource that allows reuse of code and separation of button logic from the button declaration. This walkthrough is written entirely in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
The objective of this walkthrough is to learn how to create an animated button for use in a Windows Presentation Foundation (WPF) application. This walkthrough uses styles and a template to create a customized button resource that allows reuse of code and separation of button logic from the button declaration. This walkthrough is written entirely in Extensible Application Markup Language (XAML).
> [!IMPORTANT]
> This walkthrough guides you through the steps for creating the application by typing or copying and pasting [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] into Visual Studio. If you would prefer to learn how to use a designer to create the same application, see [Create a Button by Using Microsoft Expression Blend](walkthrough-create-a-button-by-using-microsoft-expression-blend.md).
> This walkthrough guides you through the steps for creating the application by typing or copying and pasting Extensible Application Markup Language (XAML) into Visual Studio. If you would prefer to learn how to use a designer to create the same application, see [Create a Button by Using Microsoft Expression Blend](walkthrough-create-a-button-by-using-microsoft-expression-blend.md).
The following figure shows the finished buttons.
@@ -27,7 +27,7 @@ Let's start by creating a new project and adding a few buttons to the window.
2. **Create a new WPF project:** On the **File** menu, point to **New**, and then click **Project**. Find the **Windows Application (WPF)** template and name the project "AnimatedButton". This will create the skeleton for the application.
3. **Add basic default buttons:** All the files you need for this walkthrough are provided by the template. Open the Window1.xaml file by double clicking it in Solution Explorer. By default, there is a <xref:System.Windows.Controls.Grid> element in Window1.xaml. Remove the <xref:System.Windows.Controls.Grid> element and add a few buttons to the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page by typing or copy and pasting the following highlighted code to Window1.xaml:
3. **Add basic default buttons:** All the files you need for this walkthrough are provided by the template. Open the Window1.xaml file by double clicking it in Solution Explorer. By default, there is a <xref:System.Windows.Controls.Grid> element in Window1.xaml. Remove the <xref:System.Windows.Controls.Grid> element and add a few buttons to the Extensible Application Markup Language (XAML) page by typing or copy and pasting the following highlighted code to Window1.xaml:
```xaml
<Window x:Class="AnimatedButton.Window1"
@@ -12,14 +12,14 @@ As its name suggests, Windows Presentation Foundation (WPF) is great for making
![The customized button that you will create](./media/custom-button-blend-intro.jpg "custom_button_blend_Intro")
The vector graphics that make up the appearance of the button are created by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is similar to HTML except it is more powerful and extensible. [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] can be typed in manually using Visual Studio or Notepad, or you can use a visual design tool such as Blend for Visual Studio. Blend works by creating underlying XAML code, so both methods create the same graphics.
The vector graphics that make up the appearance of the button are created by using XAML is similar to HTML except it is more powerful and extensible. Extensible Application Markup Language (XAML) can be typed in manually using Visual Studio or Notepad, or you can use a visual design tool such as Blend for Visual Studio. Blend works by creating underlying XAML code, so both methods create the same graphics.
## In This Section
[Create a Button by Using Microsoft Expression Blend](walkthrough-create-a-button-by-using-microsoft-expression-blend.md)
Demonstrates how to create buttons with custom behavior by using the designer features of Expression Blend.
[Create a Button by Using XAML](walkthrough-create-a-button-by-using-xaml.md)
Demonstrates how to create buttons with custom behavior by using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and Visual Studio.
Demonstrates how to create buttons with custom behavior by using XAML and Visual Studio.
## Related Sections
[Styling and Templating](styles-templates-overview.md)
@@ -13,15 +13,15 @@ helpviewer_keywords:
ms.assetid: 214da5ef-547a-4cf8-9b07-4aa8a0e52cdd
---
# WPF Content Model
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is a presentation platform that provides many controls and control-like types whose primary purpose is to display different types of content. To determine which control to use or which control to derive from, you should understand the kinds of objects a particular control can best display.
Windows Presentation Foundation (WPF) is a presentation platform that provides many controls and control-like types whose primary purpose is to display different types of content. To determine which control to use or which control to derive from, you should understand the kinds of objects a particular control can best display.
This topic summarizes the content model for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control and control-like types. The content model describes what content can be used in a control. This topic also lists the content properties for each content model. A content property is a property that is used to store the content of the object.
This topic summarizes the content model for WPF control and control-like types. The content model describes what content can be used in a control. This topic also lists the content properties for each content model. A content property is a property that is used to store the content of the object.
<a name="classes_that_contain_arbitrary_content"></a>
## Classes That Contain Arbitrary Content
Some controls can contain an object of any type, such as a string, a <xref:System.DateTime> object, or a <xref:System.Windows.UIElement> that is a container for additional items. For example, a <xref:System.Windows.Controls.Button> can contain an image and some text; or a <xref:System.Windows.Controls.CheckBox> can contain the value of <xref:System.DateTime.Now%2A?displayProperty=nameWithType>.
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has four classes that can contain arbitrary content. The following table lists the classes, which inherit from <xref:System.Windows.Controls.Control>.
WPF has four classes that can contain arbitrary content. The following table lists the classes, which inherit from <xref:System.Windows.Controls.Control>.
|Class that contains arbitrary content|Content|
|-------------------------------------------|-------------|
@@ -209,7 +209,7 @@ TextBlock that has a Border
<a name="classes_that_provides_visual_feedback_about_a_uielement"></a>
## Classes That Provide Visual Feedback About a UIElement
The <xref:System.Windows.Documents.Adorner> class provides visual cues to a user. For example, use an <xref:System.Windows.Documents.Adorner> to add functional handles to elements or provide state information about a control. The <xref:System.Windows.Documents.Adorner> class provides a framework so that you can create your own adorners. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] does not provide any implemented adorners. For more information, see [Adorners Overview](adorners-overview.md).
The <xref:System.Windows.Documents.Adorner> class provides visual cues to a user. For example, use an <xref:System.Windows.Documents.Adorner> to add functional handles to elements or provide state information about a control. The <xref:System.Windows.Documents.Adorner> class provides a framework so that you can create your own adorners. WPF does not provide any implemented adorners. For more information, see [Adorners Overview](adorners-overview.md).
<a name="classes_that_enable_users_to_enter_text"></a>
## Classes That Enable Users to Enter Text