mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-04 00:56:03 +02:00
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:
+1
-1
@@ -44,7 +44,7 @@ In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll
|
||||
|
||||
In the .NET Framework 4 and later: PresentationHost_v0400.dll
|
||||
|
||||
**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)]
|
||||
**.NET Framework Version:** Available since 3.0
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ helpviewer_keywords:
|
||||
ms.assetid: abc8481a-f983-416f-b051-9168ac8b2ba3
|
||||
---
|
||||
# Advanced Ink Handling
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ships with the <xref:System.Windows.Controls.InkCanvas>, and is an element you can put in your application to immediately start collecting and displaying ink. However, if the <xref:System.Windows.Controls.InkCanvas> control does not provide a fine enough level of control, you can maintain control at a higher level by customizing your own ink collection and ink rendering classes using <xref:System.Windows.Input.StylusPlugIns>.
|
||||
The WPF ships with the <xref:System.Windows.Controls.InkCanvas>, and is an element you can put in your application to immediately start collecting and displaying ink. However, if the <xref:System.Windows.Controls.InkCanvas> control does not provide a fine enough level of control, you can maintain control at a higher level by customizing your own ink collection and ink rendering classes using <xref:System.Windows.Input.StylusPlugIns>.
|
||||
|
||||
The <xref:System.Windows.Input.StylusPlugIns> classes provide a mechanism for implementing low-level control over <xref:System.Windows.Input.Stylus> input and dynamically rendering ink. The <xref:System.Windows.Input.StylusPlugIns.StylusPlugIn> class provides a mechanism for you to implement custom behavior and apply it to the stream of data coming from the stylus device for optimal performance. The <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer>, a specialized <xref:System.Windows.Input.StylusPlugIns.StylusPlugIn>, allows you to customize dynamically rendering ink data in real-time which means that the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> draws digital ink immediately as <xref:System.Windows.Input.StylusPoint> data is generated, so it appears to "flow" from the stylus device.
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ helpviewer_keywords:
|
||||
ms.assetid: f0a7986e-f5b2-485c-a27d-f8e922022212
|
||||
---
|
||||
# Advanced Text Formatting
|
||||
Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. Layout and [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] APIs, such as <xref:System.Windows.Controls.TextBlock>, provide the most common and general-use elements for text presentation. Drawing APIs, such as <xref:System.Windows.Media.GlyphRunDrawing> and <xref:System.Windows.Media.FormattedText>, provide a means for including formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to control every aspect of text presentation, such as text store management, text run formatting management, and embedded object management.
|
||||
Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. Layout and user interface (UI) APIs, such as <xref:System.Windows.Controls.TextBlock>, provide the most common and general-use elements for text presentation. Drawing APIs, such as <xref:System.Windows.Media.GlyphRunDrawing> and <xref:System.Windows.Media.FormattedText>, provide a means for including formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to control every aspect of text presentation, such as text store management, text run formatting management, and embedded object management.
|
||||
|
||||
This topic provides an introduction to WPF text formatting. It focuses on client implementation and use of the WPF text formatting engine.
|
||||
|
||||
@@ -24,7 +24,7 @@ Windows Presentation Foundation (WPF) provides a robust set of APIs for includin
|
||||
|
||||
<a name="section1"></a>
|
||||
## Advanced Text Formatting
|
||||
The text layout and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] controls in WPF provide formatting properties that allow you to easily include formatted text in your application. These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text presentation in your application. However, some advanced scenarios require the control of text storage as well as text presentation. WPF provides an extensible text formatting engine for this purpose.
|
||||
The text layout and UI controls in WPF provide formatting properties that allow you to easily include formatted text in your application. These controls expose a number of properties to handle the presentation of text, which includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text presentation in your application. However, some advanced scenarios require the control of text storage as well as text presentation. WPF provides an extensible text formatting engine for this purpose.
|
||||
|
||||
The advanced text formatting features found in WPF consist of a text formatting engine, a text store, text runs, and formatting properties. The text formatting engine, <xref:System.Windows.Media.TextFormatting.TextFormatter>, creates lines of text to be used for presentation. This is achieved by initiating the line formatting process and calling the text formatter's <xref:System.Windows.Media.TextFormatting.TextFormatter.FormatLine%2A>. The text formatter retrieves text runs from your text store by calling the store's <xref:System.Windows.Media.TextFormatting.TextSource.GetTextRun%2A> method. The <xref:System.Windows.Media.TextFormatting.TextRun> objects are then formed into <xref:System.Windows.Media.TextFormatting.TextLine> objects by the text formatter and given to your application for inspection or display.
|
||||
|
||||
|
||||
+6
-6
@@ -15,13 +15,13 @@ ms.assetid: 9c6a2009-9b86-4e40-8605-0a2664dc3973
|
||||
---
|
||||
# Alignment, Margins, and Padding Overview
|
||||
|
||||
The <xref:System.Windows.FrameworkElement> class exposes several properties that are used to precisely position child elements. This topic discusses four of the most important properties: <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A>. The effects of these properties are important to understand, because they provide the basis for controlling the position of elements in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications.
|
||||
The <xref:System.Windows.FrameworkElement> class exposes several properties that are used to precisely position child elements. This topic discusses four of the most important properties: <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A>. The effects of these properties are important to understand, because they provide the basis for controlling the position of elements in Windows Presentation Foundation (WPF) applications.
|
||||
|
||||
<a name="wcpsdk_layout_amp_introduction"></a>
|
||||
|
||||
## Introduction to Element Positioning
|
||||
|
||||
There are numerous ways to position elements using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. However, achieving ideal layout goes beyond simply choosing the right <xref:System.Windows.Controls.Panel> element. Fine control of positioning requires an understanding of the <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> properties.
|
||||
There are numerous ways to position elements using WPF. However, achieving ideal layout goes beyond simply choosing the right <xref:System.Windows.Controls.Panel> element. Fine control of positioning requires an understanding of the <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> properties.
|
||||
|
||||
The following illustration shows a layout scenario that utilizes several positioning properties.
|
||||
|
||||
@@ -132,7 +132,7 @@ The <xref:System.Windows.FrameworkElement> class exposes several properties that
|
||||
|
||||
## Using Alignment, Margins, and Padding in an Application
|
||||
|
||||
<xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> provide the positioning control necessary to create a complex [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. You can use the effects of each property to change child-element positioning, enabling flexibility in creating dynamic applications and user experiences.
|
||||
<xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>, <xref:System.Windows.FrameworkElement.Margin%2A>, <xref:System.Windows.Controls.Border.Padding%2A>, and <xref:System.Windows.FrameworkElement.VerticalAlignment%2A> provide the positioning control necessary to create a complex user interface (UI). You can use the effects of each property to change child-element positioning, enabling flexibility in creating dynamic applications and user experiences.
|
||||
|
||||
The following example demonstrates each of the concepts that are detailed in this topic. Building on the infrastructure found in the first sample in this topic, this example adds a <xref:System.Windows.Controls.Grid> element as a child of the <xref:System.Windows.Controls.Border> in the first sample. <xref:System.Windows.Controls.Border.Padding%2A> is applied to the parent <xref:System.Windows.Controls.Border> element. The <xref:System.Windows.Controls.Grid> is used to partition space between three child <xref:System.Windows.Controls.StackPanel> elements. <xref:System.Windows.Controls.Button> elements are again used to show the various effects of <xref:System.Windows.FrameworkElement.Margin%2A> and <xref:System.Windows.FrameworkElement.HorizontalAlignment%2A>. <xref:System.Windows.Controls.TextBlock> elements are added to each <xref:System.Windows.Controls.ColumnDefinition> to better define the various properties applied to the <xref:System.Windows.Controls.Button> elements in each column.
|
||||
|
||||
@@ -141,7 +141,7 @@ The <xref:System.Windows.FrameworkElement> class exposes several properties that
|
||||
[!code-vb[MarginPaddingAlignmentSample#4](~/samples/snippets/visualbasic/VS_Snippets_Wpf/MarginPaddingAlignmentSample/VisualBasic/MarginPaddingAlignment.vb#4)]
|
||||
[!code-xaml[MarginPaddingAlignmentSample#4](~/samples/snippets/xaml/VS_Snippets_Wpf/MarginPaddingAlignmentSample/XAML/default.xaml#4)]
|
||||
|
||||
When compiled, the preceding application yields a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] that looks like the following illustration. The effects of the various property values are evident in the spacing between elements, and significant property values for elements in each column are shown within <xref:System.Windows.Controls.TextBlock> elements.
|
||||
When compiled, the preceding application yields a UI that looks like the following illustration. The effects of the various property values are evident in the spacing between elements, and significant property values for elements in each column are shown within <xref:System.Windows.Controls.TextBlock> elements.
|
||||
|
||||

|
||||
|
||||
@@ -149,9 +149,9 @@ The <xref:System.Windows.FrameworkElement> class exposes several properties that
|
||||
|
||||
## What's Next
|
||||
|
||||
Positioning properties defined by the <xref:System.Windows.FrameworkElement> class enable fine control of element placement within [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications. You now have several techniques you can use to better position elements using [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
|
||||
Positioning properties defined by the <xref:System.Windows.FrameworkElement> class enable fine control of element placement within WPF applications. You now have several techniques you can use to better position elements using WPF.
|
||||
|
||||
Additional resources are available that explain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout in greater detail. The [Panels Overview](../controls/panels-overview.md) topic contains more detail about the various <xref:System.Windows.Controls.Panel> elements. The topic [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) introduces advanced techniques that use layout elements to position components and bind their actions to data sources.
|
||||
Additional resources are available that explain WPF layout in greater detail. The [Panels Overview](../controls/panels-overview.md) topic contains more detail about the various <xref:System.Windows.Controls.Panel> elements. The topic [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md) introduces advanced techniques that use layout elements to position components and bind their actions to data sources.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ Writing notes or comments on paper documents is such a commonplace activity that
|
||||
|
||||

|
||||
|
||||
Users typically create annotations by first selecting some text or an item of interest, and then right-clicking to display a <xref:System.Windows.Controls.ContextMenu> of annotation options. The following example shows the [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] you can use to declare a <xref:System.Windows.Controls.ContextMenu> with routed commands that users can access to create and manage annotations.
|
||||
Users typically create annotations by first selecting some text or an item of interest, and then right-clicking to display a <xref:System.Windows.Controls.ContextMenu> of annotation options. The following example shows the Extensible Application Markup Language (XAML) you can use to declare a <xref:System.Windows.Controls.ContextMenu> with routed commands that users can access to create and manage annotations.
|
||||
|
||||
[!code-xaml[DocViewerAnnotationsXps#CreateDeleteAnnotations](~/samples/snippets/csharp/VS_Snippets_Wpf/DocViewerAnnotationsXps/CSharp/Window1.xaml#createdeleteannotations)]
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 232ad0d7-2264-4bed-aae3-10dfde116a9c
|
||||
---
|
||||
# Annotations
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides document viewing controls that support annotating document content.
|
||||
Windows Presentation Foundation (WPF) provides document viewing controls that support annotating document content.
|
||||
|
||||
## In This Section
|
||||
[Annotations Overview](annotations-overview.md)
|
||||
|
||||
@@ -12,15 +12,15 @@ ms.assetid: 75928354-dc01-47e8-a018-8409aec1f32d
|
||||
---
|
||||
# Attached Properties Overview
|
||||
|
||||
An attached property is a concept defined by XAML. An attached property is intended to be used as a type of global property that is settable on any dependency object. In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], attached properties are typically defined as a specialized form of dependency property that does not have the conventional property "wrapper".
|
||||
An attached property is a concept defined by XAML. An attached property is intended to be used as a type of global property that is settable on any dependency object. In Windows Presentation Foundation (WPF), attached properties are typically defined as a specialized form of dependency property that does not have the conventional property "wrapper".
|
||||
|
||||
## Prerequisites <a name="prerequisites"></a>
|
||||
|
||||
This article assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this article, you should also understand XAML and know how to write WPF applications.
|
||||
This article assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF) classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this article, you should also understand XAML and know how to write WPF applications.
|
||||
|
||||
## Why Use Attached Properties <a name="attached_properties_usage"></a>
|
||||
|
||||
One purpose of an attached property is to allow different child elements to specify unique values for a property that's defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. One example is the <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> property. The <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> property is created as an attached property because it is designed to be set on elements that are contained within a <xref:System.Windows.Controls.DockPanel> rather than on <xref:System.Windows.Controls.DockPanel> itself. The <xref:System.Windows.Controls.DockPanel> class defines the static <xref:System.Windows.DependencyProperty> field named <xref:System.Windows.Controls.DockPanel.DockProperty>, and then provides the <xref:System.Windows.Controls.DockPanel.GetDock%2A> and <xref:System.Windows.Controls.DockPanel.SetDock%2A> methods as public accessors for the attached property.
|
||||
One purpose of an attached property is to allow different child elements to specify unique values for a property that's defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the user interface (UI). One example is the <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> property. The <xref:System.Windows.Controls.DockPanel.Dock%2A?displayProperty=nameWithType> property is created as an attached property because it is designed to be set on elements that are contained within a <xref:System.Windows.Controls.DockPanel> rather than on <xref:System.Windows.Controls.DockPanel> itself. The <xref:System.Windows.Controls.DockPanel> class defines the static <xref:System.Windows.DependencyProperty> field named <xref:System.Windows.Controls.DockPanel.DockProperty>, and then provides the <xref:System.Windows.Controls.DockPanel.GetDock%2A> and <xref:System.Windows.Controls.DockPanel.SetDock%2A> methods as public accessors for the attached property.
|
||||
|
||||
## Attached Properties in XAML <a name="attached_properties_xaml"></a>
|
||||
|
||||
@@ -40,7 +40,7 @@ Also, because an attached property in XAML is an attribute that you set in marku
|
||||
|
||||
### Attached Property Implementation in WPF
|
||||
|
||||
In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], most of the UI-related attached properties on WPF types are implemented as dependency properties. Attached properties are a XAML concept, whereas dependency properties are a WPF concept. Because WPF attached properties are dependency properties, they support dependency property concepts such as property metadata, and default values from that property metadata.
|
||||
In Windows Presentation Foundation (WPF), most of the UI-related attached properties on WPF types are implemented as dependency properties. Attached properties are a XAML concept, whereas dependency properties are a WPF concept. Because WPF attached properties are dependency properties, they support dependency property concepts such as property metadata, and default values from that property metadata.
|
||||
|
||||
## How Attached Properties Are Used by the Owning Type <a name="howused"></a>
|
||||
|
||||
|
||||
@@ -7,20 +7,20 @@ helpviewer_keywords:
|
||||
ms.assetid: 2c997092-72c6-4767-bc84-74267f4eee72
|
||||
---
|
||||
# Base Elements Overview
|
||||
A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are <xref:System.Windows.UIElement>, <xref:System.Windows.FrameworkElement>, <xref:System.Windows.ContentElement>, and <xref:System.Windows.FrameworkContentElement>. The <xref:System.Windows.DependencyObject> class is also related, because it is a common base class of both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>
|
||||
A high percentage of classes in Windows Presentation Foundation (WPF) are derived from four classes which are commonly referred to in the SDK documentation as the base element classes. These classes are <xref:System.Windows.UIElement>, <xref:System.Windows.FrameworkElement>, <xref:System.Windows.ContentElement>, and <xref:System.Windows.FrameworkContentElement>. The <xref:System.Windows.DependencyObject> class is also related, because it is a common base class of both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>
|
||||
|
||||
<a name="base_apis"></a>
|
||||
## Base Element APIs in WPF Classes
|
||||
Both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> are derived from <xref:System.Windows.DependencyObject>, through somewhat different pathways. The split at this level deals with how a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> are used in a user interface and what purpose they serve in an application. <xref:System.Windows.UIElement> also has <xref:System.Windows.Media.Visual> in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. <xref:System.Windows.Media.Visual> provides a rendering framework by defining independent rectangular screen regions. In practice, <xref:System.Windows.UIElement> is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. <xref:System.Windows.ContentElement> does not derive from <xref:System.Windows.Media.Visual>; its model is that a <xref:System.Windows.ContentElement> would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete <xref:System.Windows.Media.Visual> for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] to consume. Certain <xref:System.Windows.UIElement> classes are intended to be content hosts: they provide the hosting and rendering for one or more <xref:System.Windows.ContentElement> classes (<xref:System.Windows.Controls.DocumentViewer> is an example of such a class). <xref:System.Windows.ContentElement> is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a <xref:System.Windows.UIElement>.
|
||||
Both <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> are derived from <xref:System.Windows.DependencyObject>, through somewhat different pathways. The split at this level deals with how a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> are used in a user interface and what purpose they serve in an application. <xref:System.Windows.UIElement> also has <xref:System.Windows.Media.Visual> in its class hierarchy, which is a class that exposes the lower-level graphics support underlying the Windows Presentation Foundation (WPF). <xref:System.Windows.Media.Visual> provides a rendering framework by defining independent rectangular screen regions. In practice, <xref:System.Windows.UIElement> is for elements that will support a larger object model, are intended to render and layout into regions that can be described as rectangular screen regions, and where the content model is deliberately more open, to allow different combinations of elements. <xref:System.Windows.ContentElement> does not derive from <xref:System.Windows.Media.Visual>; its model is that a <xref:System.Windows.ContentElement> would be consumed by something else, such as a reader or viewer that would then interpret the elements and produce the complete <xref:System.Windows.Media.Visual> for Windows Presentation Foundation (WPF) to consume. Certain <xref:System.Windows.UIElement> classes are intended to be content hosts: they provide the hosting and rendering for one or more <xref:System.Windows.ContentElement> classes (<xref:System.Windows.Controls.DocumentViewer> is an example of such a class). <xref:System.Windows.ContentElement> is used as base class for elements with somewhat smaller object models and that more address the text, information, or document content that might be hosted within a <xref:System.Windows.UIElement>.
|
||||
|
||||
### Framework-Level and Core-Level
|
||||
<xref:System.Windows.UIElement> serves as the base class for <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.ContentElement> serves as the base class for <xref:System.Windows.FrameworkContentElement>. The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] composition and layout.
|
||||
<xref:System.Windows.UIElement> serves as the base class for <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.ContentElement> serves as the base class for <xref:System.Windows.FrameworkContentElement>. The reason for this next level of classes is to support a WPF core level that is separate from a WPF framework level, with this division also existing in how the APIs are divided between the PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete solution for basic application needs, including the implementation of the layout manager for presentation. The WPF core level provides a way to use much of WPF without taking the overhead of the additional assembly. The distinction between these levels very rarely matters for most typical application development scenarios, and in general you should think of the WPF APIs as a whole and not concern yourself with the difference between WPF framework level and WPF core level. You might need to know about the level distinctions if your application design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall solution already has its own implementations of user interface (UI) composition and layout.
|
||||
|
||||
<a name="subclassing_elements"></a>
|
||||
## Choosing Which Element to Derive From
|
||||
The most practical way to create a custom class that extends [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is by deriving from one of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from.
|
||||
The most practical way to create a custom class that extends WPF is by deriving from one of the WPF classes where you get as much as possible of your desired functionality through the existing class hierarchy. This section lists the functionality that comes with three of the most important element classes to help you decide which class to inherit from.
|
||||
|
||||
If you are implementing a control, which is really one of the more common reasons for deriving from a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the <xref:System.Windows.Controls.Control> base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md).
|
||||
If you are implementing a control, which is really one of the more common reasons for deriving from a WPF class, you probably want to derive from a class that is a practical control, a control family base class, or at least from the <xref:System.Windows.Controls.Control> base class. For some guidance and practical examples, see [Control Authoring Overview](../controls/control-authoring-overview.md).
|
||||
|
||||
If you are not creating a control and need to derive from a class that is higher in the hierarchy, the following sections are intended as a guide for what characteristics are defined in each base element class.
|
||||
|
||||
@@ -76,7 +76,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t
|
||||
## Other Base Classes
|
||||
|
||||
### DispatcherObject
|
||||
<xref:System.Windows.Threading.DispatcherObject> provides support for the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] threading model and enables all objects created for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to be associated with a <xref:System.Windows.Threading.Dispatcher>. Even if you do not derive from <xref:System.Windows.UIElement>, <xref:System.Windows.DependencyObject>, or <xref:System.Windows.Media.Visual>, you should consider deriving from <xref:System.Windows.Threading.DispatcherObject> in order to get this threading model support. For more information, see [Threading Model](threading-model.md).
|
||||
<xref:System.Windows.Threading.DispatcherObject> provides support for the WPF threading model and enables all objects created for WPF applications to be associated with a <xref:System.Windows.Threading.Dispatcher>. Even if you do not derive from <xref:System.Windows.UIElement>, <xref:System.Windows.DependencyObject>, or <xref:System.Windows.Media.Visual>, you should consider deriving from <xref:System.Windows.Threading.DispatcherObject> in order to get this threading model support. For more information, see [Threading Model](threading-model.md).
|
||||
|
||||
### Visual
|
||||
<xref:System.Windows.Media.Visual> implements the concept of a 2D object that generally requires visual presentation in a roughly rectangular region. The actual rendering of a <xref:System.Windows.Media.Visual> happens in other classes (it is not self-contained), but the <xref:System.Windows.Media.Visual> class provides a known type that is used by rendering processes at various levels. <xref:System.Windows.Media.Visual> implements hit testing, but it does not expose events that report hit-testing positives (these are in <xref:System.Windows.UIElement>). For more information, see [Visual Layer Programming](../graphics-multimedia/visual-layer-programming.md).
|
||||
@@ -89,7 +89,7 @@ A high percentage of classes in [!INCLUDE[TLA#tla_winclient](../../../includes/t
|
||||
<xref:System.Windows.Media.Animation.Animatable> is a <xref:System.Windows.Freezable> derived class that specifically adds the animation control layer and some utility members so that currently animated properties can be distinguished from nonanimated properties.
|
||||
|
||||
### Control
|
||||
<xref:System.Windows.Controls.Control> is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that <xref:System.Windows.Controls.Control> enables is control templating.
|
||||
<xref:System.Windows.Controls.Control> is the intended base class for the type of object that is variously termed a control or component, depending on the technology. In general, WPF control classes are classes that either directly represent a UI control or participate closely in control composition. The primary functionality that <xref:System.Windows.Controls.Control> enables is control templating.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
+15
-15
@@ -8,7 +8,7 @@ ms.assetid: fd850e25-7dba-408c-b521-8873e51dc968
|
||||
---
|
||||
# Bidirectional Features in WPF Overview
|
||||
|
||||
Unlike any other development platform, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has many features that support rapid development of bidirectional content, for example, mixed left to right and right to left data in the same document. At the same time, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] creates an excellent experience for users who require bidirectional features such as Arabic and Hebrew speaking users.
|
||||
Unlike any other development platform, WPF has many features that support rapid development of bidirectional content, for example, mixed left to right and right to left data in the same document. At the same time, WPF creates an excellent experience for users who require bidirectional features such as Arabic and Hebrew speaking users.
|
||||
|
||||
The following sections explain many bidirectional features together with examples illustrating how to achieve the best display of bidirectional content. Most of the samples use XAML, though you can easily apply the concepts to C# or Microsoft Visual Basic code.
|
||||
|
||||
@@ -16,7 +16,7 @@ The following sections explain many bidirectional features together with example
|
||||
|
||||
## FlowDirection
|
||||
|
||||
The basic property that defines the content flow direction in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application is <xref:System.Windows.FrameworkElement.FlowDirection%2A>. This property can be set to one of two enumeration values, <xref:System.Windows.FlowDirection.LeftToRight> or <xref:System.Windows.FlowDirection.RightToLeft>. The property is available to all [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements that inherit from <xref:System.Windows.FrameworkElement>.
|
||||
The basic property that defines the content flow direction in a WPF application is <xref:System.Windows.FrameworkElement.FlowDirection%2A>. This property can be set to one of two enumeration values, <xref:System.Windows.FlowDirection.LeftToRight> or <xref:System.Windows.FlowDirection.RightToLeft>. The property is available to all WPF elements that inherit from <xref:System.Windows.FrameworkElement>.
|
||||
|
||||
The following examples set the flow direction of a <xref:System.Windows.Controls.TextBox> element.
|
||||
|
||||
@@ -32,7 +32,7 @@ The following graphic shows how the previous code renders.
|
||||
|
||||

|
||||
|
||||
An element within a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] tree will inherit the <xref:System.Windows.FrameworkElement.FlowDirection%2A> from its container. In the following example, the <xref:System.Windows.Controls.TextBlock> is inside a <xref:System.Windows.Controls.Grid>, which resides in a <xref:System.Windows.Window>. Setting the <xref:System.Windows.FrameworkElement.FlowDirection%2A> for the <xref:System.Windows.Window> implies setting it for the <xref:System.Windows.Controls.Grid> and <xref:System.Windows.Controls.TextBlock> as well.
|
||||
An element within a user interface (UI) tree will inherit the <xref:System.Windows.FrameworkElement.FlowDirection%2A> from its container. In the following example, the <xref:System.Windows.Controls.TextBlock> is inside a <xref:System.Windows.Controls.Grid>, which resides in a <xref:System.Windows.Window>. Setting the <xref:System.Windows.FrameworkElement.FlowDirection%2A> for the <xref:System.Windows.Window> implies setting it for the <xref:System.Windows.Controls.Grid> and <xref:System.Windows.Controls.TextBlock> as well.
|
||||
|
||||
The following example demonstrates setting <xref:System.Windows.FrameworkElement.FlowDirection%2A>.
|
||||
|
||||
@@ -50,7 +50,7 @@ The following graphic shows the output of the previous example:
|
||||
|
||||
Many development platforms such as HTML, Win32 and Java provide special support for bidirectional content development. Markup languages such as HTML give content writers the necessary markup to display text in any required direction, for example the HTML 4.0 tag, "dir" that takes "rtl" or "ltr" as values. This tag is similar to the <xref:System.Windows.FrameworkElement.FlowDirection%2A> property, but the <xref:System.Windows.FrameworkElement.FlowDirection%2A> property works in a more advanced way to layout textual content and can be used for content other than text.
|
||||
|
||||
In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], a <xref:System.Windows.Documents.FlowDocument> is a versatile [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element that can host a combination of text, tables, images and other elements. The samples in the following sections use this element.
|
||||
In UI element that can host a combination of text, tables, images and other elements. The samples in the following sections use this element.
|
||||
|
||||
Adding text to a <xref:System.Windows.Documents.FlowDocument> can be done in more that one way. A simple way to do so is through a <xref:System.Windows.Documents.Paragraph> which is a block-level element used to group content such as text. To add text to inline-level elements the samples use <xref:System.Windows.Documents.Span> and <xref:System.Windows.Documents.Run>. <xref:System.Windows.Documents.Span> is an inline-level flow content element used for grouping other inline elements, while a <xref:System.Windows.Documents.Run> is an inline-level flow content element intended to contain a run of unformatted text. A <xref:System.Windows.Documents.Span> can contain multiple <xref:System.Windows.Documents.Run> elements.
|
||||
|
||||
@@ -92,7 +92,7 @@ The following graphic shows another example that uses numbers and arithmetic exp
|
||||
|
||||
Users of this application will be disappointed by the output, even though the <xref:System.Windows.FlowDirection> is correct the numbers are not shaped as Arabic numbers should be shaped.
|
||||
|
||||
XAML elements can include an XML attribute (`xml:lang`) that defines the language of each element. XAML also supports a XML language principle whereby `xml:lang` values applied to parent elements in the tree are used by child elements. In the previous example, because a language was not defined for the <xref:System.Windows.Documents.Run> element or any of its top level elements, the default `xml:lang` was used, which is `en-US` for XAML. The internal number shaping algorithm of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] selects numbers in the corresponding language – in this case English. To make the Arabic numbers render correctly `xml:lang` needs to be set.
|
||||
XAML elements can include an XML attribute (`xml:lang`) that defines the language of each element. XAML also supports a XML language principle whereby `xml:lang` values applied to parent elements in the tree are used by child elements. In the previous example, because a language was not defined for the <xref:System.Windows.Documents.Run> element or any of its top level elements, the default `xml:lang` was used, which is `en-US` for XAML. The internal number shaping algorithm of Windows Presentation Foundation (WPF) selects numbers in the corresponding language – in this case English. To make the Arabic numbers render correctly `xml:lang` needs to be set.
|
||||
|
||||
The following graphic shows the example with `xml:lang` added.
|
||||
|
||||
@@ -108,7 +108,7 @@ Be aware that many languages have different `xml:lang` values depending on the t
|
||||
|
||||
## FlowDirection with Non-text Elements
|
||||
|
||||
<xref:System.Windows.FlowDirection> defines not only how text flows in a textual element but also the flow direction of almost every other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element. The following graphic shows a <xref:System.Windows.Controls.ToolBar> that uses a horizontal <xref:System.Windows.Media.LinearGradientBrush> to draw its background with a left to right gradient.
|
||||
<xref:System.Windows.FlowDirection> defines not only how text flows in a textual element but also the flow direction of almost every other UI element. The following graphic shows a <xref:System.Windows.Controls.ToolBar> that uses a horizontal <xref:System.Windows.Media.LinearGradientBrush> to draw its background with a left to right gradient.
|
||||
|
||||

|
||||
|
||||
@@ -132,7 +132,7 @@ There are a few cases where <xref:System.Windows.FlowDirection> does not behave
|
||||
|
||||
An <xref:System.Windows.Controls.Image> represents a control that displays an image. In XAML it can be used with a <xref:System.Windows.Controls.Image.Source%2A> property that defines the uniform resource identifier (URI) of the <xref:System.Windows.Controls.Image> to display.
|
||||
|
||||
Unlike other [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements, an <xref:System.Windows.Controls.Image> does not inherit the <xref:System.Windows.FlowDirection> from the container. However, if the <xref:System.Windows.FlowDirection> is set explicitly to <xref:System.Windows.FlowDirection.RightToLeft>, an <xref:System.Windows.Controls.Image> is displayed flipped horizontally. This is implemented as a convenient feature for developers of bidirectional content; because in some cases, horizontally flipping the image produces the desired effect.
|
||||
Unlike other UI elements, an <xref:System.Windows.Controls.Image> does not inherit the <xref:System.Windows.FlowDirection> from the container. However, if the <xref:System.Windows.FlowDirection> is set explicitly to <xref:System.Windows.FlowDirection.RightToLeft>, an <xref:System.Windows.Controls.Image> is displayed flipped horizontally. This is implemented as a convenient feature for developers of bidirectional content; because in some cases, horizontally flipping the image produces the desired effect.
|
||||
|
||||
The following graphic shows a flipped <xref:System.Windows.Controls.Image>.
|
||||
|
||||
@@ -160,7 +160,7 @@ The following graphic shows the output of the previous example with arrows drawn
|
||||
|
||||

|
||||
|
||||
The <xref:System.Windows.Controls.Image> and <xref:System.Windows.Shapes.Path> are two examples of a how [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] uses <xref:System.Windows.FlowDirection>. Beside laying out [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] elements in a specific direction within a container, <xref:System.Windows.FlowDirection> can be used with elements such as <xref:System.Windows.Controls.InkPresenter> which renders ink on a surface, <xref:System.Windows.Media.LinearGradientBrush>, <xref:System.Windows.Media.RadialGradientBrush>. Whenever you need a right to left behavior for your content that mimics a left to right behavior, or vice versa, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides that capability.
|
||||
The <xref:System.Windows.Controls.Image> and <xref:System.Windows.Shapes.Path> are two examples of a how UI elements in a specific direction within a container, <xref:System.Windows.FlowDirection> can be used with elements such as <xref:System.Windows.Controls.InkPresenter> which renders ink on a surface, <xref:System.Windows.Media.LinearGradientBrush>, <xref:System.Windows.Media.RadialGradientBrush>. Whenever you need a right to left behavior for your content that mimics a left to right behavior, or vice versa, Windows Presentation Foundation (WPF) provides that capability.
|
||||
|
||||
<a name="NumberSubstitution"></a>
|
||||
|
||||
@@ -170,9 +170,9 @@ Historically, Windows has supported number substitution by allowing the represen
|
||||
|
||||
This has allowed applications to process numerical values without the need to convert them from one language to another, for example a user can open an Microsoft Excel spreadsheet in a localized Arabic Windows and see the numbers shaped in Arabic, but open it in a European version of Windows and see European representation of the same numbers. This is also necessary for other symbols such as comma separators and percentage symbol because they usually accompany numbers in the same document.
|
||||
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] continues the same tradition, and adds further support for this feature that allows more user control over when and how substitution is used. While this feature is designed for any language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a challenge for application developers because of the various cultures an application might run on.
|
||||
Windows Presentation Foundation (WPF) continues the same tradition, and adds further support for this feature that allows more user control over when and how substitution is used. While this feature is designed for any language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a challenge for application developers because of the various cultures an application might run on.
|
||||
|
||||
The core property controlling how number substitution works in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is the <xref:System.Windows.Media.NumberSubstitution.Substitution%2A> dependency property. The <xref:System.Windows.Media.NumberSubstitution> class specifies how numbers in text are to be displayed. It has three public properties that define its behavior. The following is a summary of each of the properties:
|
||||
The core property controlling how number substitution works in Windows Presentation Foundation (WPF) is the <xref:System.Windows.Media.NumberSubstitution.Substitution%2A> dependency property. The <xref:System.Windows.Media.NumberSubstitution> class specifies how numbers in text are to be displayed. It has three public properties that define its behavior. The following is a summary of each of the properties:
|
||||
|
||||
**CultureSource:**
|
||||
|
||||
@@ -202,7 +202,7 @@ This property specifies the type of number substitution to perform. It takes one
|
||||
|
||||
- <xref:System.Windows.Media.NumberSubstitutionMethod.Traditional>: Numbers are rendered using the traditional digits for the number culture. For most cultures, this is the same as <xref:System.Windows.Media.NumberSubstitutionMethod.NativeNational>. However, <xref:System.Windows.Media.NumberSubstitutionMethod.NativeNational> results in Latin digits for some Arabic cultures, whereas this value results in Arabic digits for all Arabic cultures.
|
||||
|
||||
What do those values mean for a bidirectional content developer? In most cases, the developer might need only to define <xref:System.Windows.FlowDirection> and the language of each textual [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] element, for example `Language="ar-SA"` and the <xref:System.Windows.Media.NumberSubstitution> logic takes care of displaying the numbers according to the correct [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. The following example demonstrates using Arabic and English numbers in a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application running in an Arabic version of Windows.
|
||||
What do those values mean for a bidirectional content developer? In most cases, the developer might need only to define <xref:System.Windows.FlowDirection> and the language of each textual UI element, for example `Language="ar-SA"` and the <xref:System.Windows.Media.NumberSubstitution> logic takes care of displaying the numbers according to the correct UI. The following example demonstrates using Arabic and English numbers in a Windows Presentation Foundation (WPF) application running in an Arabic version of Windows.
|
||||
|
||||
[!code-xaml[Numbers#Numbers](~/samples/snippets/csharp/VS_Snippets_Wpf/Numbers/CS/Window1.xaml#numbers)]
|
||||
|
||||
@@ -214,11 +214,11 @@ The <xref:System.Windows.FlowDirection> was important in this case because setti
|
||||
|
||||
**Defining Substitution Rules**
|
||||
|
||||
In a real application you might need to set the Language programmatically. For example, you want to set the `xml:lang` attribute to be the same as the one used by the system’s [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], or maybe change the language depending on the application state.
|
||||
In a real application you might need to set the Language programmatically. For example, you want to set the `xml:lang` attribute to be the same as the one used by the system’s UI, or maybe change the language depending on the application state.
|
||||
|
||||
If you want to make changes based on the application's state, make use of other features provided by [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|
||||
If you want to make changes based on the application's state, make use of other features provided by Windows Presentation Foundation (WPF).
|
||||
|
||||
First, set the application component’s `NumberSubstitution.CultureSource="Text"`. Using this setting makes sure that the settings do not come from the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for text elements that have "User" as the default, such as <xref:System.Windows.Controls.TextBlock>.
|
||||
First, set the application component’s `NumberSubstitution.CultureSource="Text"`. Using this setting makes sure that the settings do not come from the UI for text elements that have "User" as the default, such as <xref:System.Windows.Controls.TextBlock>.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -257,7 +257,7 @@ The following graphic shows what the window looks like for either programming la
|
||||
|
||||
**Using the Substitution Property**
|
||||
|
||||
The way number substitution works in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] depends on both the Language of the text element and its <xref:System.Windows.FlowDirection>. If the <xref:System.Windows.FlowDirection> is left to right, then European digits are rendered. However if it is preceded by Arabic text, or has the language set to "ar" and the <xref:System.Windows.FlowDirection> is <xref:System.Windows.FlowDirection.RightToLeft>, Arabic digits are rendered instead.
|
||||
The way number substitution works in Windows Presentation Foundation (WPF) depends on both the Language of the text element and its <xref:System.Windows.FlowDirection>. If the <xref:System.Windows.FlowDirection> is left to right, then European digits are rendered. However if it is preceded by Arabic text, or has the language set to "ar" and the <xref:System.Windows.FlowDirection> is <xref:System.Windows.FlowDirection.RightToLeft>, Arabic digits are rendered instead.
|
||||
|
||||
In some cases, however, you might want to create a unified application, for example European digits for all users. Or Arabic digits in <xref:System.Windows.Documents.Table> cells with a specific <xref:System.Windows.Style>. One easy way to do that is using the <xref:System.Windows.Media.NumberSubstitution.Substitution%2A> property.
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ Defers a property value to be a data-bound value, creating an intermediate expre
|
||||
Describing data binding at a basic level is not covered in this topic. See [Data Binding Overview](../data/data-binding-overview.md).
|
||||
|
||||
> [!NOTE]
|
||||
> <xref:System.Windows.Data.MultiBinding> and <xref:System.Windows.Data.PriorityBinding> do not support a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] extension syntax. You would instead use property elements. See reference topics for <xref:System.Windows.Data.MultiBinding> and <xref:System.Windows.Data.PriorityBinding>.
|
||||
> <xref:System.Windows.Data.MultiBinding> and <xref:System.Windows.Data.PriorityBinding> do not support a XAML extension syntax. You would instead use property elements. See reference topics for <xref:System.Windows.Data.MultiBinding> and <xref:System.Windows.Data.PriorityBinding>.
|
||||
|
||||
Boolean values for XAML are case insensitive. For example you could specify either `{Binding NotifyOnValidationError=true}` or `{Binding NotifyOnValidationError=True}`.
|
||||
|
||||
|
||||
@@ -7,17 +7,17 @@ helpviewer_keywords:
|
||||
ms.assetid: 7e2392e0-75dc-463d-a716-908772782431
|
||||
---
|
||||
# ClearType Overview
|
||||
This topic provides an overview of the Microsoft ClearType technology found in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|
||||
This topic provides an overview of the Microsoft ClearType technology found in the Windows Presentation Foundation (WPF).
|
||||
|
||||
<a name="overview"></a>
|
||||
## Technology Overview
|
||||
ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. Before ClearType, the smallest level of detail that a computer could display was a single pixel, but with ClearType running on an LCD monitor, we can now display features of text as small as a fraction of a pixel in width. The extra resolution increases the sharpness of the tiny details in text display, making it much easier to read over long durations.
|
||||
|
||||
The ClearType available in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is the latest generation of ClearType which has several improvements over version found in Microsoft Windows Graphics Device Interface (GDI).
|
||||
The ClearType available in Windows Presentation Foundation (WPF) is the latest generation of ClearType which has several improvements over version found in Microsoft Windows Graphics Device Interface (GDI).
|
||||
|
||||
<a name="sub-pixel_positioning"></a>
|
||||
## Sub-pixel Positioning
|
||||
A significant improvement over the previous version of ClearType is the use of sub-pixel positioning. Unlike the ClearType implementation found in GDI, the ClearType found in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] allows glyphs to start within the pixel and not just the beginning boundary of the pixel. Because of this extra resolution in positioning glyphs, the spacing and proportions of the glyphs is more precise and consistent.
|
||||
A significant improvement over the previous version of ClearType is the use of sub-pixel positioning. Unlike the ClearType implementation found in GDI, the ClearType found in Windows Presentation Foundation (WPF) allows glyphs to start within the pixel and not just the beginning boundary of the pixel. Because of this extra resolution in positioning glyphs, the spacing and proportions of the glyphs is more precise and consistent.
|
||||
|
||||
The following two examples show how glyphs may begin on any sub-pixel boundary when sub-pixel positioning is used. The example on the left is rendered using the earlier version of the ClearType renderer, which did not employ sub-pixel positioning. The example on the right is rendered using the new version of the ClearType renderer, using sub-pixel positioning. Note how each **e** and **l** in the right-hand image is rendered slightly differently because each starts on a different sub-pixel. When viewing the text at its normal size on the screen, this difference is not noticeable because of the high contrast of the glyph image. This is only possible because of sophisticated color filtering that is incorporated in ClearType.
|
||||
|
||||
@@ -31,14 +31,14 @@ Text with earlier and later versions of ClearType
|
||||
|
||||
<a name="y-direction_antialiasing"></a>
|
||||
## Y-Direction Antialiasing
|
||||
Another improvement of ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] is y-direction anti-aliasing. The ClearType in GDI without y-direction anti-aliasing provides better resolution on the x-axis but not the y-axis. On the tops and bottoms of shallow curves, the jagged edges detract from its readability.
|
||||
Another improvement of ClearType in Windows Presentation Foundation (WPF) is y-direction anti-aliasing. The ClearType in GDI without y-direction anti-aliasing provides better resolution on the x-axis but not the y-axis. On the tops and bottoms of shallow curves, the jagged edges detract from its readability.
|
||||
|
||||
The following example shows the effect of having no y-direction antialiasing. In this case, the jagged edges on the top and bottom of the letter are apparent.
|
||||
|
||||

|
||||
Text with jagged edges on shallow curves
|
||||
|
||||
ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides antialiasing on the y-direction level to smooth out any jagged edges. This is particularly important for improving the readability of East Asian languages where ideographs have an almost equal amount of horizontal and vertical shallow curves.
|
||||
ClearType in Windows Presentation Foundation (WPF) provides antialiasing on the y-direction level to smooth out any jagged edges. This is particularly important for improving the readability of East Asian languages where ideographs have an almost equal amount of horizontal and vertical shallow curves.
|
||||
|
||||
The following example shows the effect of y-direction antialiasing. In this case, the top and bottom of the letter show a smooth curve.
|
||||
|
||||
@@ -47,11 +47,11 @@ Text with ClearType y-direction antialiasing
|
||||
|
||||
<a name="hardware_acceleration"></a>
|
||||
## Hardware Acceleration
|
||||
ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] can take advantage of hardware acceleration for better performance and to reduce CPU load and system memory requirements. By using the pixel shaders and video memory of a graphics card, ClearType provides faster rendering of text, particularly when animation is used.
|
||||
ClearType in Windows Presentation Foundation (WPF) can take advantage of hardware acceleration for better performance and to reduce CPU load and system memory requirements. By using the pixel shaders and video memory of a graphics card, ClearType provides faster rendering of text, particularly when animation is used.
|
||||
|
||||
ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] does not modify the system-wide ClearType settings. Disabling ClearType in Windows sets [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] antialiasing to grayscale mode. In addition, ClearType in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] does not modify the settings of the [ClearType Tuner PowerToy](https://www.microsoft.com/typography/ClearTypePowerToy.mspx).
|
||||
ClearType in Windows Presentation Foundation (WPF) does not modify the system-wide ClearType settings. Disabling ClearType in Windows sets Windows Presentation Foundation (WPF) antialiasing to grayscale mode. In addition, ClearType in Windows Presentation Foundation (WPF) does not modify the settings of the [ClearType Tuner PowerToy](https://www.microsoft.com/typography/ClearTypePowerToy.mspx).
|
||||
|
||||
One of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] architectural design decisions is to have resolution independent layout better support higher resolution DPI monitors, which are becoming more widespread. This has the consequence of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] not supporting aliased text rendering or the bitmaps in some East Asian fonts because they are both resolution dependent.
|
||||
One of the Windows Presentation Foundation (WPF) architectural design decisions is to have resolution independent layout better support higher resolution DPI monitors, which are becoming more widespread. This has the consequence of Windows Presentation Foundation (WPF) not supporting aliased text rendering or the bitmaps in some East Asian fonts because they are both resolution dependent.
|
||||
|
||||
<a name="further_information"></a>
|
||||
## Further Information
|
||||
|
||||
@@ -11,7 +11,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha
|
||||
|
||||
<a name="overview"></a>
|
||||
## Technology Overview
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications that render text to a display device use ClearType features to provide an enhanced reading experience. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. For more information on ClearType, see [ClearType Overview](cleartype-overview.md).
|
||||
WPF applications that render text to a display device use ClearType features to provide an enhanced reading experience. ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. For more information on ClearType, see [ClearType Overview](cleartype-overview.md).
|
||||
|
||||
Text that is rendered with ClearType can appear significantly different when viewed on various display devices. For example, a small number of monitors implement the color stripe elements in blue, green, red order rather than the more common red, green, blue (RGB) order.
|
||||
|
||||
@@ -21,7 +21,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha
|
||||
|
||||
<a name="registry_settings"></a>
|
||||
## Registry Settings
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] specifies four registry settings for controlling ClearType features:
|
||||
WPF specifies four registry settings for controlling ClearType features:
|
||||
|
||||
|Setting|Description|
|
||||
|-------------|-----------------|
|
||||
@@ -30,9 +30,9 @@ This topic provides an overview of the Microsoft ClearType registry settings tha
|
||||
|Pixel structure|Describes the arrangement of pixels for a display device.|
|
||||
|Text contrast level|Describes the level of contrast for displayed text.|
|
||||
|
||||
These settings can be accessed by an external configuration utility that knows how to reference the identified [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ClearType registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor.
|
||||
These settings can be accessed by an external configuration utility that knows how to reference the identified WPF ClearType registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor.
|
||||
|
||||
If the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] ClearType registry settings are not set (which is the default state), the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application queries the Windows system parameters information for font smoothing settings.
|
||||
If the WPF ClearType registry settings are not set (which is the default state), the WPF application queries the Windows system parameters information for font smoothing settings.
|
||||
|
||||
> [!NOTE]
|
||||
> For information on enumerating display device names, see the `SystemParametersInfo`Win32 function.
|
||||
@@ -53,7 +53,7 @@ This topic provides an overview of the Microsoft ClearType registry settings tha
|
||||

|
||||
|
||||
> [!NOTE]
|
||||
> [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications render text in one of either two modes, with and without ClearType. When text is rendered without ClearType, it is referred to as gray scale rendering.
|
||||
> WPF applications render text in one of either two modes, with and without ClearType. When text is rendered without ClearType, it is referred to as gray scale rendering.
|
||||
|
||||
<a name="gamma_level"></a>
|
||||
## Gamma Level
|
||||
|
||||
@@ -7,7 +7,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 9df6d3c9-aed3-471c-af36-6859b19d999f
|
||||
---
|
||||
# Code-Behind and XAML in WPF
|
||||
<a name="introduction"></a> Code-behind is a term used to describe the code that is joined with markup-defined objects, when a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is markup-compiled. This topic describes requirements for code-behind as well as an alternative inline code mechanism for code in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
|
||||
<a name="introduction"></a> Code-behind is a term used to describe the code that is joined with markup-defined objects, when a XAML page is markup-compiled. This topic describes requirements for code-behind as well as an alternative inline code mechanism for code in XAML.
|
||||
|
||||
This topic contains the following sections:
|
||||
|
||||
@@ -36,21 +36,21 @@ ms.assetid: 9df6d3c9-aed3-471c-af36-6859b19d999f
|
||||
|
||||
- Note that under the default behavior of the markup compile build actions, you can leave the derivation blank in the partial class definition on the code-behind side. The compiled result will assume the page root's backing type to be the basis for the partial class, even if it not specified. However, relying on this behavior is not a best practice.
|
||||
|
||||
- The event handlers you write in the code-behind must be instance methods and cannot be static methods. These methods must be defined by the partial class within the CLR namespace identified by `x:Class`. You cannot qualify the name of an event handler to instruct a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor to look for an event handler for event wiring in a different class scope.
|
||||
- The event handlers you write in the code-behind must be instance methods and cannot be static methods. These methods must be defined by the partial class within the CLR namespace identified by `x:Class`. You cannot qualify the name of an event handler to instruct a XAML processor to look for an event handler for event wiring in a different class scope.
|
||||
|
||||
- The handler must match the delegate for the appropriate event in the backing type system.
|
||||
|
||||
- For the Microsoft Visual Basic language specifically, you can use the language-specific `Handles` keyword to associate handlers with instances and events in the handler declaration, instead of attaching handlers with attributes in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. However, this technique does have some limitations because the `Handles` keyword cannot support all of the specific features of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system, such as certain routed event scenarios or attached events. For details, see [Visual Basic and WPF Event Handling](visual-basic-and-wpf-event-handling.md).
|
||||
- For the Microsoft Visual Basic language specifically, you can use the language-specific `Handles` keyword to associate handlers with instances and events in the handler declaration, instead of attaching handlers with attributes in WPF event system, such as certain routed event scenarios or attached events. For details, see [Visual Basic and WPF Event Handling](visual-basic-and-wpf-event-handling.md).
|
||||
|
||||
<a name="x_Code"></a>
|
||||
## x:Code
|
||||
[x:Code](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type) is a directive element defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. An `x:Code` directive element can contain inline programming code. The code that is defined inline can interact with the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] on the same page. The following example illustrates inline C# code. Notice that the code is inside the `x:Code` element and that the code must be surrounded by `<CDATA[`...`]]>` to escape the contents for XML, so that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor (interpreting either the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] schema or the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] schema) will not try to interpret the contents literally as XML.
|
||||
[x:Code](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type) is a directive element defined in WPF schema) will not try to interpret the contents literally as XML.
|
||||
|
||||
[!code-xaml[XAMLOvwSupport#ButtonWithInlineCode](~/samples/snippets/csharp/VS_Snippets_Wpf/XAMLOvwSupport/CSharp/page4.xaml#buttonwithinlinecode)]
|
||||
|
||||
<a name="Inline_Code_Limitations"></a>
|
||||
## Inline Code Limitations
|
||||
You should consider avoiding or limiting the use of inline code. In terms of architecture and coding philosophy, maintaining a separation between markup and code-behind keeps the designer and developer roles much more distinct. On a more technical level, the code that you write for inline code can be awkward to write, because you are always writing into the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] generated partial class, and can only use the default XML namespace mappings. Because you cannot add `using` statements, you must fully qualify many of the API calls that you make. The default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] mappings include most but not all CLR namespaces that are present in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] assemblies; you will have to fully qualify calls to types and members contained within the other CLR namespaces. You also cannot define anything beyond the partial class in the inline code, and all user code entities you reference must exist as a member or variable within the generated partial class. Other language specific programming features, such as macros or `#ifdef` against global variables or build variables, are also not available. For more information, see [x:Code Intrinsic XAML Type](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type).
|
||||
You should consider avoiding or limiting the use of inline code. In terms of architecture and coding philosophy, maintaining a separation between markup and code-behind keeps the designer and developer roles much more distinct. On a more technical level, the code that you write for inline code can be awkward to write, because you are always writing into the WPF mappings include most but not all CLR namespaces that are present in the WPF assemblies; you will have to fully qualify calls to types and members contained within the other CLR namespaces. You also cannot define anything beyond the partial class in the inline code, and all user code entities you reference must exist as a member or variable within the generated partial class. Other language specific programming features, such as macros or `#ifdef` against global variables or build variables, are also not available. For more information, see [x:Code Intrinsic XAML Type](/dotnet/desktop/xaml-services/xcode-intrinsic-xaml-type).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
+1
-1
@@ -29,7 +29,7 @@ Provides a way to specify a bitmap source that does not have an embedded profile
|
||||
|
||||
Attribute syntax is the most common syntax used with this markup extension. `ColorConvertedBitmap` (or `ColorConvertedBitmapExtension`) cannot be used in property element syntax, because the values can only be set as values on the initial constructor, which is the string following the extension identifier.
|
||||
|
||||
`ColorConvertedBitmap` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
`ColorConvertedBitmap` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -18,9 +18,9 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
---
|
||||
# Commanding Overview
|
||||
|
||||
<a name="introduction"></a> Commanding is an input mechanism in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] which provides input handling at a more semantic level than device input. Examples of commands are the **Copy**, **Cut**, and **Paste** operations found on many applications.
|
||||
<a name="introduction"></a> Commanding is an input mechanism in Windows Presentation Foundation (WPF) which provides input handling at a more semantic level than device input. Examples of commands are the **Copy**, **Cut**, and **Paste** operations found on many applications.
|
||||
|
||||
This overview defines what commands are in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], which classes are part of the commanding model, and how to use and create commands in your applications.
|
||||
This overview defines what commands are in WPF, which classes are part of the commanding model, and how to use and create commands in your applications.
|
||||
|
||||
This topic contains the following sections:
|
||||
|
||||
@@ -48,7 +48,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## Simple Command Example in WPF
|
||||
|
||||
The simplest way to use a command in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is to use a predefined <xref:System.Windows.Input.RoutedCommand> from one of the command library classes; use a control that has native support for handling the command; and use a control that has native support for invoking a command. The <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command is one of the predefined commands in the <xref:System.Windows.Input.ApplicationCommands> class. The <xref:System.Windows.Controls.TextBox> control has built in logic for handling the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command. And the <xref:System.Windows.Controls.MenuItem> class has native support for invoking commands.
|
||||
The simplest way to use a command in WPF is to use a predefined <xref:System.Windows.Input.RoutedCommand> from one of the command library classes; use a control that has native support for handling the command; and use a control that has native support for invoking a command. The <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command is one of the predefined commands in the <xref:System.Windows.Input.ApplicationCommands> class. The <xref:System.Windows.Controls.TextBox> control has built in logic for handling the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command. And the <xref:System.Windows.Controls.MenuItem> class has native support for invoking commands.
|
||||
|
||||
The following example shows how to set up a <xref:System.Windows.Controls.MenuItem> so that when it is clicked it will invoke the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command on a <xref:System.Windows.Controls.TextBox>, assuming the <xref:System.Windows.Controls.TextBox> has keyboard focus.
|
||||
|
||||
@@ -61,7 +61,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## Four Main Concepts in WPF Commanding
|
||||
|
||||
The routed command model in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can be broken up into four main concepts: the command, the command source, the command target, and the command binding:
|
||||
The routed command model in WPF can be broken up into four main concepts: the command, the command source, the command target, and the command binding:
|
||||
|
||||
- The *command* is the action to be executed.
|
||||
|
||||
@@ -77,13 +77,13 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
### Commands
|
||||
|
||||
Commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are created by implementing the <xref:System.Windows.Input.ICommand> interface. <xref:System.Windows.Input.ICommand> exposes two methods, <xref:System.Windows.Input.ICommand.Execute%2A>, and <xref:System.Windows.Input.ICommand.CanExecute%2A>, and an event, <xref:System.Windows.Input.ICommand.CanExecuteChanged>. <xref:System.Windows.Input.ICommand.Execute%2A> performs the actions that are associated with the command. <xref:System.Windows.Input.ICommand.CanExecute%2A> determines whether the command can execute on the current command target. <xref:System.Windows.Input.ICommand.CanExecuteChanged> is raised if the command manager that centralizes the commanding operations detects a change in the command source that might invalidate a command that has been raised but not yet executed by the command binding. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of <xref:System.Windows.Input.ICommand> is the <xref:System.Windows.Input.RoutedCommand> class and is the focus of this overview.
|
||||
Commands in WPF are created by implementing the <xref:System.Windows.Input.ICommand> interface. <xref:System.Windows.Input.ICommand> exposes two methods, <xref:System.Windows.Input.ICommand.Execute%2A>, and <xref:System.Windows.Input.ICommand.CanExecute%2A>, and an event, <xref:System.Windows.Input.ICommand.CanExecuteChanged>. <xref:System.Windows.Input.ICommand.Execute%2A> performs the actions that are associated with the command. <xref:System.Windows.Input.ICommand.CanExecute%2A> determines whether the command can execute on the current command target. <xref:System.Windows.Input.ICommand.CanExecuteChanged> is raised if the command manager that centralizes the commanding operations detects a change in the command source that might invalidate a command that has been raised but not yet executed by the command binding. The WPF implementation of <xref:System.Windows.Input.ICommand> is the <xref:System.Windows.Input.RoutedCommand> class and is the focus of this overview.
|
||||
|
||||
The main sources of input in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a <xref:System.Windows.RoutedEvent> to notify objects in an application page that an input event has occurred. A <xref:System.Windows.Input.RoutedCommand> is no different. The <xref:System.Windows.Input.RoutedCommand.Execute%2A> and <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> methods of a <xref:System.Windows.Input.RoutedCommand> do not contain the application logic for the command, but rather they raise routed events that tunnel and bubble through the element tree until they encounter an object with a <xref:System.Windows.Input.CommandBinding>. The <xref:System.Windows.Input.CommandBinding> contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Routed Events Overview](routed-events-overview.md).
|
||||
The main sources of input in WPF are the mouse, the keyboard, ink, and routed commands. The more device-oriented inputs use a <xref:System.Windows.RoutedEvent> to notify objects in an application page that an input event has occurred. A <xref:System.Windows.Input.RoutedCommand> is no different. The <xref:System.Windows.Input.RoutedCommand.Execute%2A> and <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> methods of a <xref:System.Windows.Input.RoutedCommand> do not contain the application logic for the command, but rather they raise routed events that tunnel and bubble through the element tree until they encounter an object with a <xref:System.Windows.Input.CommandBinding>. The <xref:System.Windows.Input.CommandBinding> contains the handlers for these events and it is the handlers that perform the command. For more information on event routing in WPF, see [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
The <xref:System.Windows.Input.RoutedCommand.Execute%2A> method on a <xref:System.Windows.Input.RoutedCommand> raises the <xref:System.Windows.Input.CommandManager.PreviewExecuted> and the <xref:System.Windows.Input.CommandManager.Executed> events on the command target. The <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> method on a <xref:System.Windows.Input.RoutedCommand> raises the <xref:System.Windows.Input.CommandManager.CanExecute> and <xref:System.Windows.Input.CommandManager.PreviewCanExecute> events on the command target. These events tunnel and bubble through the element tree until they encounter an object which has a <xref:System.Windows.Input.CommandBinding> for that particular command.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supplies a set of common routed commands spread across several classes: <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.ComponentCommands>, and <xref:System.Windows.Documents.EditingCommands>. These classes consist only of the <xref:System.Windows.Input.RoutedCommand> objects and not the implementation logic of the command. The implementation logic is the responsibility of the object on which the command is being executed on.
|
||||
WPF supplies a set of common routed commands spread across several classes: <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.ComponentCommands>, and <xref:System.Windows.Documents.EditingCommands>. These classes consist only of the <xref:System.Windows.Input.RoutedCommand> objects and not the implementation logic of the command. The implementation logic is the responsibility of the object on which the command is being executed on.
|
||||
|
||||
<a name="Command_Sources"></a>
|
||||
|
||||
@@ -91,17 +91,17 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
A command source is the object which invokes the command. Examples of command sources are <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Controls.Button>, and <xref:System.Windows.Input.KeyGesture>.
|
||||
|
||||
Command sources in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] generally implement the <xref:System.Windows.Input.ICommandSource> interface.
|
||||
Command sources in WPF generally implement the <xref:System.Windows.Input.ICommandSource> interface.
|
||||
|
||||
<xref:System.Windows.Input.ICommandSource> exposes three properties: <xref:System.Windows.Input.ICommandSource.Command%2A>, <xref:System.Windows.Input.ICommandSource.CommandTarget%2A>, and <xref:System.Windows.Input.ICommandSource.CommandParameter%2A>:
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.Command%2A> is the command to execute when the command source is invoked.
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is the object on which to execute the command. It is worth noting that in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is not set, the element with keyboard focus will be the command target.
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is the object on which to execute the command. It is worth noting that in WPF the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is not set, the element with keyboard focus will be the command target.
|
||||
|
||||
- <xref:System.Windows.Input.ICommandSource.CommandParameter%2A> is a user-defined data type used to pass information to the handlers implementing the command.
|
||||
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes that implement <xref:System.Windows.Input.ICommandSource> are <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Documents.Hyperlink>, and <xref:System.Windows.Input.InputBinding>. <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, and <xref:System.Windows.Documents.Hyperlink> invoke a command when they are clicked, and an <xref:System.Windows.Input.InputBinding> invokes a command when the <xref:System.Windows.Input.InputGesture> associated with it is performed.
|
||||
The WPF classes that implement <xref:System.Windows.Input.ICommandSource> are <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Documents.Hyperlink>, and <xref:System.Windows.Input.InputBinding>. <xref:System.Windows.Controls.Primitives.ButtonBase>, <xref:System.Windows.Controls.MenuItem>, and <xref:System.Windows.Documents.Hyperlink> invoke a command when they are clicked, and an <xref:System.Windows.Input.InputBinding> invokes a command when the <xref:System.Windows.Input.InputGesture> associated with it is performed.
|
||||
|
||||
The following example shows how to use a <xref:System.Windows.Controls.MenuItem> in a <xref:System.Windows.Controls.ContextMenu> as a command source for the <xref:System.Windows.Input.ApplicationCommands.Properties%2A> command.
|
||||
|
||||
@@ -112,7 +112,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
Typically, a command source will listen to the <xref:System.Windows.Input.RoutedCommand.CanExecuteChanged> event. This event informs the command source that the ability of the command to execute on the current command target may have changed. The command source can query the current status of the <xref:System.Windows.Input.RoutedCommand> by using the <xref:System.Windows.Input.RoutedCommand.CanExecute%2A> method. The command source can then disable itself if the command cannot execute. An example of this is a <xref:System.Windows.Controls.MenuItem> graying itself out when a command cannot execute.
|
||||
|
||||
An <xref:System.Windows.Input.InputGesture> can be used as a command source. Two types of input gestures in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are the <xref:System.Windows.Input.KeyGesture> and <xref:System.Windows.Input.MouseGesture>. You can think of a <xref:System.Windows.Input.KeyGesture> as a keyboard shortcut, such as CTRL+C. A <xref:System.Windows.Input.KeyGesture> is comprised of a <xref:System.Windows.Input.Key> and a set of <xref:System.Windows.Input.ModifierKeys>. A <xref:System.Windows.Input.MouseGesture> is comprised of a <xref:System.Windows.Input.MouseAction> and an optional set of <xref:System.Windows.Input.ModifierKeys>.
|
||||
An <xref:System.Windows.Input.InputGesture> can be used as a command source. Two types of input gestures in WPF are the <xref:System.Windows.Input.KeyGesture> and <xref:System.Windows.Input.MouseGesture>. You can think of a <xref:System.Windows.Input.KeyGesture> as a keyboard shortcut, such as CTRL+C. A <xref:System.Windows.Input.KeyGesture> is comprised of a <xref:System.Windows.Input.Key> and a set of <xref:System.Windows.Input.ModifierKeys>. A <xref:System.Windows.Input.MouseGesture> is comprised of a <xref:System.Windows.Input.MouseAction> and an optional set of <xref:System.Windows.Input.ModifierKeys>.
|
||||
|
||||
In order for an <xref:System.Windows.Input.InputGesture> to act as a command source, it must be associated with a command. There are a few ways to accomplish this. One way is to use an <xref:System.Windows.Input.InputBinding>.
|
||||
|
||||
@@ -163,7 +163,7 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
### Command Target
|
||||
|
||||
The command target is the element on which the command is executed. With regards to a <xref:System.Windows.Input.RoutedCommand>, the command target is the element at which routing of the <xref:System.Windows.Input.CommandManager.Executed> and <xref:System.Windows.Input.CommandManager.CanExecute> starts. As noted previously, in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored.
|
||||
The command target is the element on which the command is executed. With regards to a <xref:System.Windows.Input.RoutedCommand>, the command target is the element at which routing of the <xref:System.Windows.Input.CommandManager.Executed> and <xref:System.Windows.Input.CommandManager.CanExecute> starts. As noted previously, in WPF the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> property on <xref:System.Windows.Input.ICommandSource> is only applicable when the <xref:System.Windows.Input.ICommand> is a <xref:System.Windows.Input.RoutedCommand>. If the <xref:System.Windows.Input.ICommandSource.CommandTarget%2A> is set on an <xref:System.Windows.Input.ICommandSource> and the corresponding command is not a <xref:System.Windows.Input.RoutedCommand>, the command target is ignored.
|
||||
|
||||
The command source can explicitly set the command target. If the command target is not defined, the element with keyboard focus will be used as the command target. One of the benefits of using the element with keyboard focus as the command target is that it allows the application developer to use the same command source to invoke a command on multiple targets without having to keep track of the command target. For example, if a <xref:System.Windows.Controls.MenuItem> invokes the **Paste** command in an application that has a <xref:System.Windows.Controls.TextBox> control and a <xref:System.Windows.Controls.PasswordBox> control, the target can be either the <xref:System.Windows.Controls.TextBox> or <xref:System.Windows.Controls.PasswordBox> depending on which control has keyboard focus.
|
||||
|
||||
@@ -186,11 +186,11 @@ ms.assetid: bc208dfe-367d-426a-99de-52b7e7511e81
|
||||
|
||||
## Command Library
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a set of predefined commands. The command library consists of the following classes: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Documents.EditingCommands>, and the <xref:System.Windows.Input.ComponentCommands>. These classes provide commands such as <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.NavigationCommands.BrowseBack%2A> and <xref:System.Windows.Input.NavigationCommands.BrowseForward%2A>, <xref:System.Windows.Input.MediaCommands.Play%2A>, <xref:System.Windows.Input.MediaCommands.Stop%2A>, and <xref:System.Windows.Input.MediaCommands.Pause%2A>.
|
||||
WPF provides a set of predefined commands. The command library consists of the following classes: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Documents.EditingCommands>, and the <xref:System.Windows.Input.ComponentCommands>. These classes provide commands such as <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.NavigationCommands.BrowseBack%2A> and <xref:System.Windows.Input.NavigationCommands.BrowseForward%2A>, <xref:System.Windows.Input.MediaCommands.Play%2A>, <xref:System.Windows.Input.MediaCommands.Stop%2A>, and <xref:System.Windows.Input.MediaCommands.Pause%2A>.
|
||||
|
||||
Many of these commands include a set of default input bindings. For example, if you specify that your application handles the copy command, you automatically get the keyboard binding "CTRL+C" You also get bindings for other input devices, such as Tablet PC pen gestures and speech information.
|
||||
|
||||
When you reference commands in the various command libraries using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can usually omit the class name of the library class that exposes the static command property. Generally, the command names are unambiguous as strings, and the owning types exist to provide a logical grouping of commands but are not necessary for disambiguation. For instance, you can specify `Command="Cut"` rather than the more verbose `Command="ApplicationCommands.Cut"`. This is a convenience mechanism that is built in to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor for commands (more precisely, it is a type converter behavior of <xref:System.Windows.Input.ICommand>, which the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor references at load time).
|
||||
When you reference commands in the various command libraries using WPF WPF XAML processor references at load time).
|
||||
|
||||
<a name="creating_commands"></a>
|
||||
|
||||
|
||||
+2
-2
@@ -65,9 +65,9 @@ Defines and references keys for resources that are loaded from external assembli
|
||||
|
||||
`ComponentResourceKey` can be used in object element syntax. In this case, specifying the value of both the <xref:System.Windows.ComponentResourceKey.TypeInTargetAssembly%2A> and <xref:System.Windows.ComponentResourceKey.ResourceId%2A> properties is required to properly initialize the extension.
|
||||
|
||||
In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader implementation, the handling for this markup extension is defined by the <xref:System.Windows.ComponentResourceKey> class.
|
||||
In the WPF XAML reader implementation, the handling for this markup extension is defined by the <xref:System.Windows.ComponentResourceKey> class.
|
||||
|
||||
`ComponentResourceKey` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
`ComponentResourceKey` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
+1
-1
@@ -42,7 +42,7 @@ HRESULT CreateIDispatchSTAForwarder(
|
||||
|
||||
In the .NET Framework 4 and later: PresentationHost_v0400.dll
|
||||
|
||||
**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)]
|
||||
**.NET Framework Version:** Available since 3.0
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -19,33 +19,33 @@ ms.assetid: e6bfcfac-b10d-4f58-9f77-a864c2a2938f
|
||||
---
|
||||
# Custom Dependency Properties
|
||||
|
||||
This topic describes the reasons that [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application developers and component authors might want to create custom dependency property, and describes the implementation steps as well as some implementation options that can improve performance, usability, or versatility of the property.
|
||||
This topic describes the reasons that Windows Presentation Foundation (WPF) application developers and component authors might want to create custom dependency property, and describes the implementation steps as well as some implementation options that can improve performance, usability, or versatility of the property.
|
||||
|
||||
<a name="prerequisites"></a>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md) topic. In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications.
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md) topic. In order to follow the examples in this topic, you should also understand WPF applications.
|
||||
|
||||
<a name="whatis"></a>
|
||||
|
||||
## What Is a Dependency Property?
|
||||
|
||||
You can enable what would otherwise be a common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Dependency properties are properties that are registered with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system by calling the <xref:System.Windows.DependencyProperty.Register%2A> method (or <xref:System.Windows.DependencyProperty.RegisterReadOnly%2A>), and that are backed by a <xref:System.Windows.DependencyProperty> identifier field. Dependency properties can be used only by <xref:System.Windows.DependencyObject> types, but <xref:System.Windows.DependencyObject> is quite high in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class hierarchy, so the majority of classes available in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] can support dependency properties. For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see [Dependency Properties Overview](dependency-properties-overview.md).
|
||||
You can enable what would otherwise be a common language runtime (CLR) property to support styling, data binding, inheritance, animations, and default values by implementing it as a dependency property. Dependency properties are properties that are registered with the WPF property system by calling the <xref:System.Windows.DependencyProperty.Register%2A> method (or <xref:System.Windows.DependencyProperty.RegisterReadOnly%2A>), and that are backed by a <xref:System.Windows.DependencyProperty> identifier field. Dependency properties can be used only by <xref:System.Windows.DependencyObject> types, but <xref:System.Windows.DependencyObject> is quite high in the WPF class hierarchy, so the majority of classes available in WPF can support dependency properties. For more information about dependency properties and some of the terminology and conventions used for describing them in this SDK, see [Dependency Properties Overview](dependency-properties-overview.md).
|
||||
|
||||
<a name="example_dp"></a>
|
||||
|
||||
## Examples of Dependency Properties
|
||||
|
||||
Examples of dependency properties that are implemented on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes include the <xref:System.Windows.Controls.Control.Background%2A> property, the <xref:System.Windows.FrameworkElement.Width%2A> property, and the <xref:System.Windows.Controls.TextBox.Text%2A> property, among many others. Each dependency property exposed by a class has a corresponding public static field of type <xref:System.Windows.DependencyProperty> exposed on that same class. This is the identifier for the dependency property. The identifier is named using a convention: the name of the dependency property with the string `Property` appended to it. For example, the corresponding <xref:System.Windows.DependencyProperty> identifier field for the <xref:System.Windows.Controls.Control.Background%2A> property is <xref:System.Windows.Controls.Control.BackgroundProperty>. The identifier stores the information about the dependency property as it was registered, and the identifier is then used later for other operations involving the dependency property, such as calling <xref:System.Windows.DependencyObject.SetValue%2A>.
|
||||
Examples of dependency properties that are implemented on WPF classes include the <xref:System.Windows.Controls.Control.Background%2A> property, the <xref:System.Windows.FrameworkElement.Width%2A> property, and the <xref:System.Windows.Controls.TextBox.Text%2A> property, among many others. Each dependency property exposed by a class has a corresponding public static field of type <xref:System.Windows.DependencyProperty> exposed on that same class. This is the identifier for the dependency property. The identifier is named using a convention: the name of the dependency property with the string `Property` appended to it. For example, the corresponding <xref:System.Windows.DependencyProperty> identifier field for the <xref:System.Windows.Controls.Control.Background%2A> property is <xref:System.Windows.Controls.Control.BackgroundProperty>. The identifier stores the information about the dependency property as it was registered, and the identifier is then used later for other operations involving the dependency property, such as calling <xref:System.Windows.DependencyObject.SetValue%2A>.
|
||||
|
||||
As mentioned in the [Dependency Properties Overview](dependency-properties-overview.md), all dependency properties in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] (except most attached properties) are also CLR properties because of the "wrapper" implementation. Therefore, from code, you can get or set dependency properties by calling CLR accessors that define the wrappers in the same manner that you would use other CLR properties. As a consumer of established dependency properties, you do not typically use the <xref:System.Windows.DependencyObject> methods <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A>, which are the connection point to the underlying property system. Rather, the existing implementation of the CLR properties will have already called <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> within the `get` and `set` wrapper implementations of the property, using the identifier field appropriately. If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.
|
||||
As mentioned in the [Dependency Properties Overview](dependency-properties-overview.md), all dependency properties in WPF (except most attached properties) are also CLR properties because of the "wrapper" implementation. Therefore, from code, you can get or set dependency properties by calling CLR accessors that define the wrappers in the same manner that you would use other CLR properties. As a consumer of established dependency properties, you do not typically use the <xref:System.Windows.DependencyObject> methods <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A>, which are the connection point to the underlying property system. Rather, the existing implementation of the CLR properties will have already called <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> within the `get` and `set` wrapper implementations of the property, using the identifier field appropriately. If you are implementing a custom dependency property yourself, then you will be defining the wrapper in a similar way.
|
||||
|
||||
<a name="backing_with_dp"></a>
|
||||
|
||||
## When Should You Implement a Dependency Property?
|
||||
|
||||
When you implement a property on a class, so long as your class derives from <xref:System.Windows.DependencyObject>, you have the option to back your property with a <xref:System.Windows.DependencyProperty> identifier and thus to make it a dependency property. Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Sometimes, the typical technique of backing your property with a private field is adequate. However, you should implement your property as a dependency property whenever you want your property to support one or more of the following [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] capabilities:
|
||||
When you implement a property on a class, so long as your class derives from <xref:System.Windows.DependencyObject>, you have the option to back your property with a <xref:System.Windows.DependencyProperty> identifier and thus to make it a dependency property. Having your property be a dependency property is not always necessary or appropriate, and will depend on your scenario needs. Sometimes, the typical technique of backing your property with a private field is adequate. However, you should implement your property as a dependency property whenever you want your property to support one or more of the following WPF capabilities:
|
||||
|
||||
- You want your property to be settable in a style. For more information, see [Styling and Templating](../controls/styles-templates-overview.md).
|
||||
|
||||
@@ -59,11 +59,11 @@ When you implement a property on a class, so long as your class derives from <xr
|
||||
|
||||
- You want the property system to report when the previous value of the property has been changed by actions taken by the property system, the environment, or the user, or by reading and using styles. By using property metadata, your property can specify a callback method that will be invoked each time the property system determines that your property value was definitively changed. A related concept is property value coercion. For more information, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md).
|
||||
|
||||
- You want to use established metadata conventions that are also used by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] processes, such as reporting whether changing a property value should require the layout system to recompose the visuals for an element. Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.
|
||||
- You want to use established metadata conventions that are also used by WPF processes, such as reporting whether changing a property value should require the layout system to recompose the visuals for an element. Or you want to be able to use metadata overrides so that derived classes can change metadata-based characteristics such as the default value.
|
||||
|
||||
- You want properties of a custom control to receive Visual Studio WPF Designer support, such as **Properties** window editing. For more information, see [Control Authoring Overview](../controls/control-authoring-overview.md).
|
||||
|
||||
When you examine these scenarios, you should also consider whether you can achieve your scenario by overriding the metadata of an existing dependency property, rather than implementing a completely new property. Whether a metadata override is practical depends on your scenario and how closely that scenario resembles the implementation in existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dependency properties and classes. For more information about overriding metadata on existing properties, see [Dependency Property Metadata](dependency-property-metadata.md).
|
||||
When you examine these scenarios, you should also consider whether you can achieve your scenario by overriding the metadata of an existing dependency property, rather than implementing a completely new property. Whether a metadata override is practical depends on your scenario and how closely that scenario resembles the implementation in existing WPF dependency properties and classes. For more information about overriding metadata on existing properties, see [Dependency Property Metadata](dependency-property-metadata.md).
|
||||
|
||||
<a name="checklist"></a>
|
||||
|
||||
@@ -96,7 +96,7 @@ There are established naming conventions regarding dependency properties that yo
|
||||
|
||||
The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given as the first parameter of <xref:System.Windows.DependencyProperty.Register%2A>. That name must be unique within each registering type. Dependency properties inherited through base types are considered to be already part of the registering type; names of inherited properties cannot be registered again. However, there is a technique for adding a class as owner of a dependency property even when that dependency property is not inherited; for details, see [Dependency Property Metadata](dependency-property-metadata.md).
|
||||
|
||||
When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix `Property`. This field is your identifier for the dependency property, and it will be used later as an input for the <xref:System.Windows.DependencyObject.SetValue%2A> and <xref:System.Windows.DependencyObject.GetValue%2A> calls you will make in the wrappers, by any other code access to the property by your own code, by any external code access you allow, by the property system, and potentially by [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processors.
|
||||
When you create the identifier field, name this field by the name of the property as you registered it, plus the suffix `Property`. This field is your identifier for the dependency property, and it will be used later as an input for the <xref:System.Windows.DependencyObject.SetValue%2A> and <xref:System.Windows.DependencyObject.GetValue%2A> calls you will make in the wrappers, by any other code access to the property by your own code, by any external code access you allow, by the property system, and potentially by XAML processors.
|
||||
|
||||
> [!NOTE]
|
||||
> Defining the dependency property in the class body is the typical implementation, but it is also possible to define a dependency property in the class static constructor. This approach might make sense if you need more than one line of code to initialize the dependency property.
|
||||
@@ -109,7 +109,7 @@ Your wrapper implementation should call <xref:System.Windows.DependencyObject.Ge
|
||||
|
||||
In all but exceptional circumstances, your wrapper implementations should perform only the <xref:System.Windows.DependencyObject.GetValue%2A> and <xref:System.Windows.DependencyObject.SetValue%2A> actions, respectively. The reason for this is discussed in the topic [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md).
|
||||
|
||||
All existing public dependency properties that are provided on the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes use this simple wrapper implementation model; most of the complexity of how dependency properties work is either inherently a behavior of the property system, or is implemented through other concepts such as coercion or property change callbacks through property metadata.
|
||||
All existing public dependency properties that are provided on the WPF classes use this simple wrapper implementation model; most of the complexity of how dependency properties work is either inherently a behavior of the property system, or is implemented through other concepts such as coercion or property change callbacks through property metadata.
|
||||
|
||||
[!code-csharp[WPFAquariumSln#AGWithWrapper](~/samples/snippets/csharp/VS_Snippets_Wpf/WPFAquariumSln/CSharp/WPFAquariumObjects/Class1.cs#agwithwrapper)]
|
||||
[!code-vb[WPFAquariumSln#AGWithWrapper](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WPFAquariumSln/visualbasic/wpfaquariumobjects/class1.vb#agwithwrapper)]
|
||||
@@ -118,9 +118,9 @@ Again, by convention, the name of the wrapper property must be the same as the n
|
||||
|
||||
- Certain aspects of styles and templates will not work.
|
||||
|
||||
- Most tools and designers must rely on the naming conventions to properly serialize [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], or to provide designer environment assistance at a per-property level.
|
||||
- Most tools and designers must rely on the naming conventions to properly serialize XAML, or to provide designer environment assistance at a per-property level.
|
||||
|
||||
- The current implementation of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. For more information, see [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md).
|
||||
- The current implementation of the WPF XAML loader bypasses the wrappers entirely, and relies on the naming convention when processing attribute values. For more information, see [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md).
|
||||
|
||||
<a name="metadata"></a>
|
||||
|
||||
@@ -134,11 +134,11 @@ For <xref:System.Windows.FrameworkPropertyMetadata>, you can also specify metada
|
||||
|
||||
#### Setting Appropriate Metadata Flags
|
||||
|
||||
- If your property (or changes in its value) affects the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsMeasure>, <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsArrange>, <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsRender>.
|
||||
- If your property (or changes in its value) affects the user interface (UI), and in particular affects how the layout system should size or render your element in a page, set one or more of the following flags: <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsMeasure>, <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsArrange>, <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsRender>.
|
||||
|
||||
- <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsMeasure> indicates that a change to this property requires a change to [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] rendering where the containing object might require more or less space within the parent. For example, a "Width" property should have this flag set.
|
||||
- <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsMeasure> indicates that a change to this property requires a change to UI rendering where the containing object might require more or less space within the parent. For example, a "Width" property should have this flag set.
|
||||
|
||||
- <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsArrange> indicates that a change to this property requires a change to [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. For example, an "Alignment" property should have this flag set.
|
||||
- <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsArrange> indicates that a change to this property requires a change to UI rendering that typically does not require a change in the dedicated space, but does indicate that the positioning within the space has changed. For example, an "Alignment" property should have this flag set.
|
||||
|
||||
- <xref:System.Windows.FrameworkPropertyMetadataOptions.AffectsRender> indicates that some other change has occurred that will not affect layout and measure, but does require another render. An example would be a property that changes a color of an existing element, such as "Background".
|
||||
|
||||
@@ -176,7 +176,7 @@ Dependency properties should be declared as public properties. Dependency proper
|
||||
|
||||
## Dependency Properties and Class Constructors
|
||||
|
||||
There is a general principle in managed code programming (often enforced by code analysis tools such as FxCop) that class constructors should not call virtual methods. This is because constructors can be called as base initialization of a derived class constructor, and entering the virtual method through the constructor might occur at an incomplete initialization state of the object instance being constructed. When you derive from any class that already derives from <xref:System.Windows.DependencyObject>, you should be aware that the property system itself calls and exposes virtual methods internally. These virtual methods are part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system services. Overriding the methods enables derived classes to participate in value determination. To avoid potential issues with runtime initialization, you should not set dependency property values within constructors of classes, unless you follow a very specific constructor pattern. For details, see [Safe Constructor Patterns for DependencyObjects](safe-constructor-patterns-for-dependencyobjects.md).
|
||||
There is a general principle in managed code programming (often enforced by code analysis tools such as FxCop) that class constructors should not call virtual methods. This is because constructors can be called as base initialization of a derived class constructor, and entering the virtual method through the constructor might occur at an incomplete initialization state of the object instance being constructed. When you derive from any class that already derives from <xref:System.Windows.DependencyObject>, you should be aware that the property system itself calls and exposes virtual methods internally. These virtual methods are part of the WPF property system services. Overriding the methods enables derived classes to participate in value determination. To avoid potential issues with runtime initialization, you should not set dependency property values within constructors of classes, unless you follow a very specific constructor pattern. For details, see [Safe Constructor Patterns for DependencyObjects](safe-constructor-patterns-for-dependencyobjects.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ The <xref:System.Windows.Ink.Stroke.DrawingAttributes%2A> property of a stroke a
|
||||
|
||||
<a name="ImplementingADynamicRenderer"></a>
|
||||
## Implementing a Dynamic Renderer
|
||||
Although the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> class is a standard part of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], to perform more specialized rendering, you must create a customized dynamic renderer that derives from the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> and override the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer.OnDraw%2A> method.
|
||||
Although the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> class is a standard part of WPF, to perform more specialized rendering, you must create a customized dynamic renderer that derives from the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> and override the <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer.OnDraw%2A> method.
|
||||
|
||||
The following example demonstrates a customized <xref:System.Windows.Input.StylusPlugIns.DynamicRenderer> that draws ink with a linear gradient brush effect.
|
||||
|
||||
|
||||
@@ -30,9 +30,9 @@ Data that is transferred as part of a drag-and-drop operation is stored in a dat
|
||||
|<xref:System.Windows.IDataObject.GetFormats%2A>|Returns a list of formats that the data in this data object is stored in, or can be converted to.|
|
||||
|<xref:System.Windows.IDataObject.SetData%2A>|Stores the specified data in this data object.|
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a basic implementation of <xref:System.Windows.IDataObject> in the <xref:System.Windows.DataObject> class. The stock <xref:System.Windows.DataObject> class is sufficient for many common data transfer scenarios.
|
||||
WPF provides a basic implementation of <xref:System.Windows.IDataObject> in the <xref:System.Windows.DataObject> class. The stock <xref:System.Windows.DataObject> class is sufficient for many common data transfer scenarios.
|
||||
|
||||
There are several pre-defined formats, such as bitmap, CSV, file, HTML, RTF, string, text, and audio. For information about pre-defined data formats provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see the <xref:System.Windows.DataFormats> class reference topic.
|
||||
There are several pre-defined formats, such as bitmap, CSV, file, HTML, RTF, string, text, and audio. For information about pre-defined data formats provided with WPF, see the <xref:System.Windows.DataFormats> class reference topic.
|
||||
|
||||
Data objects commonly include a facility for automatically converting data stored in one format to a different format while extracting data; this facility is referred to as auto-convert. When querying for the data formats available in a data object, auto-convertible data formats can be filtered from native data formats by calling the <xref:System.Windows.DataObject.GetFormats%28System.Boolean%29> or <xref:System.Windows.DataObject.GetDataPresent%28System.String%2CSystem.Boolean%29> method and specifying the `autoConvert` parameter as `false`. When adding data to a data object with the <xref:System.Windows.DataObject.SetData%28System.String%2CSystem.Object%2CSystem.Boolean%29> method, auto-conversion of data can be prohibited by setting the `autoConvert` parameter to `false`.
|
||||
|
||||
|
||||
+1
-1
@@ -30,7 +30,7 @@ void Deactivate()
|
||||
|
||||
In the .NET Framework 4 and later: PresentationHost_v0400.dll
|
||||
|
||||
**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)]
|
||||
**.NET Framework Version:** Available since 3.0
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -121,7 +121,7 @@ The following example sets the <xref:System.Windows.Controls.ContentControl.Cont
|
||||
Dependency properties, or the <xref:System.Windows.DependencyObject> class, do not natively support <xref:System.ComponentModel.INotifyPropertyChanged> for purposes of producing notifications of changes in <xref:System.Windows.DependencyObject> source property value for data binding operations. For more information on how to create properties for use in data binding that can report changes to a data binding target, see [Data Binding Overview](../data/data-binding-overview.md).
|
||||
|
||||
### Styles
|
||||
Styles and templates are two of the chief motivating scenarios for using dependency properties. Styles are particularly useful for setting properties that define application [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. Styles are typically defined as resources in XAML. Styles interact with the property system because they typically contain "setters" for particular properties, as well as "triggers" that change a property value based on the real-time value for another property.
|
||||
Styles and templates are two of the chief motivating scenarios for using dependency properties. Styles are particularly useful for setting properties that define application user interface (UI). Styles are typically defined as resources in XAML. Styles interact with the property system because they typically contain "setters" for particular properties, as well as "triggers" that change a property value based on the real-time value for another property.
|
||||
|
||||
The following example creates a simple style (which would be defined inside a <xref:System.Windows.FrameworkElement.Resources%2A> dictionary, not shown), then applies that style directly to the <xref:System.Windows.FrameworkElement.Style%2A> property for a <xref:System.Windows.Controls.Button>. The setter within the style sets the <xref:System.Windows.Controls.Control.Background%2A> property for a styled <xref:System.Windows.Controls.Button> to green.
|
||||
|
||||
@@ -185,7 +185,7 @@ Typically, you would not want styles to always apply and to obscure even a local
|
||||
|
||||
## Learning more about dependency properties
|
||||
|
||||
- An attached property is a type of property that supports a specialized syntax in XAML. An attached property often does not have a 1:1 correspondence with a common language runtime (CLR) property, and is not necessarily a dependency property. The typical purpose of an attached property is to allow child elements to report property values to a parent element, even if the parent element and child element do not both possess that property as part of the class members listings. One primary scenario is to enable child elements to inform the parent how they should be presented in [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]; for an example, see <xref:System.Windows.Controls.DockPanel.Dock%2A> or <xref:System.Windows.Controls.Canvas.Left%2A>. For details, see [Attached Properties Overview](attached-properties-overview.md).
|
||||
- An attached property is a type of property that supports a specialized syntax in XAML. An attached property often does not have a 1:1 correspondence with a common language runtime (CLR) property, and is not necessarily a dependency property. The typical purpose of an attached property is to allow child elements to report property values to a parent element, even if the parent element and child element do not both possess that property as part of the class members listings. One primary scenario is to enable child elements to inform the parent how they should be presented in UI; for an example, see <xref:System.Windows.Controls.DockPanel.Dock%2A> or <xref:System.Windows.Controls.Canvas.Left%2A>. For details, see [Attached Properties Overview](attached-properties-overview.md).
|
||||
|
||||
- Component developers or application developers may wish to create their own dependency property, in order to enable capabilities such as data binding or styles support, or for invalidation and value coercion support. For details, see [Custom Dependency Properties](custom-dependency-properties.md).
|
||||
|
||||
|
||||
@@ -9,11 +9,11 @@ helpviewer_keywords:
|
||||
ms.assetid: d01ed009-b722-41bf-b82f-fe1a8cdc50dd
|
||||
---
|
||||
# Dependency Property Metadata
|
||||
The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class.
|
||||
The Windows Presentation Foundation (WPF) property system includes a metadata reporting system that goes beyond what can be reported about a property through reflection or general common language runtime (CLR) characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a dependency property, can be changed when the dependency property is added to a different class, and can be specifically overridden by all derived classes that inherit the dependency property from the defining base class.
|
||||
|
||||
<a name="prerequisites"></a>
|
||||
## Prerequisites
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). In order to follow the examples in this topic, you should also understand [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications.
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF applications.
|
||||
|
||||
<a name="dp_metadata_contents"></a>
|
||||
## How Dependency Property Metadata is Used
|
||||
@@ -36,9 +36,9 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]
|
||||
|
||||
<a name="override_or_subclass"></a>
|
||||
## When to Override Metadata, When to Derive a Class
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member.
|
||||
The WPF property system has established capabilities for changing some characteristics of dependency properties without requiring them to be entirely re-implemented. This is accomplished by constructing a different instance of property metadata for the dependency property as it exists on a particular type. Note that most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on inherited classes could only be accomplished by shadowing the existing member.
|
||||
|
||||
If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. A custom dependency property behaves identically to dependency properties defined by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs. For more details about custom dependency properties, see [Custom Dependency Properties](custom-dependency-properties.md).
|
||||
If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, and then to declare a custom dependency property on your derived class. A custom dependency property behaves identically to dependency properties defined by the WPF APIs. For more details about custom dependency properties, see [Custom Dependency Properties](custom-dependency-properties.md).
|
||||
|
||||
One notable characteristic of a dependency property that you cannot override is its value type. If you are inheriting a dependency property that has the approximate behavior you require, but you require a different type for it, you will have to implement a custom dependency property and perhaps link the properties through type conversion or other implementation on your custom class. Also, you cannot replace an existing <xref:System.Windows.ValidateValueCallback>, because this callback exists in the registration field itself and not within its metadata.
|
||||
|
||||
@@ -52,7 +52,7 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]
|
||||
### Overriding Metadata
|
||||
The purpose of overriding metadata is primarily so that you have the opportunity to change the various metadata-derived behaviors that are applied to the dependency property as it exists on your type. The reasons for this are explained in more detail in the [Metadata](#dp_metadata_contents) section. For more information including some code examples, see [Override Metadata for a Dependency Property](how-to-override-metadata-for-a-dependency-property.md).
|
||||
|
||||
Property metadata can be supplied for a dependency property during the registration call (<xref:System.Windows.DependencyProperty.Register%2A>). However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. You can do this by calling the <xref:System.Windows.DependencyProperty.OverrideMetadata%2A> method. For an example from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs, the <xref:System.Windows.FrameworkElement> class is the type that first registers the <xref:System.Windows.UIElement.Focusable%2A> dependency property. But the <xref:System.Windows.Controls.Control> class overrides metadata for the dependency property to provide its own initial default value, changing it from `false` to `true`, and otherwise re-uses the original <xref:System.Windows.UIElement.Focusable%2A> implementation.
|
||||
Property metadata can be supplied for a dependency property during the registration call (<xref:System.Windows.DependencyProperty.Register%2A>). However, in many cases, you might want to provide type-specific metadata for your class when it inherits that dependency property. You can do this by calling the <xref:System.Windows.DependencyProperty.OverrideMetadata%2A> method. For an example from the WPF APIs, the <xref:System.Windows.FrameworkElement> class is the type that first registers the <xref:System.Windows.UIElement.Focusable%2A> dependency property. But the <xref:System.Windows.Controls.Control> class overrides metadata for the dependency property to provide its own initial default value, changing it from `false` to `true`, and otherwise re-uses the original <xref:System.Windows.UIElement.Focusable%2A> implementation.
|
||||
|
||||
When you override metadata, the different metadata characteristics are either merged or replaced.
|
||||
|
||||
@@ -69,7 +69,7 @@ The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]
|
||||
This behavior is implemented by <xref:System.Windows.PropertyMetadata.Merge%2A>, and can be overridden on derived metadata classes.
|
||||
|
||||
#### Overriding Attached Property Metadata
|
||||
In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], attached properties are implemented as dependency properties. This means that they also have property metadata, which individual classes can override. The scoping considerations for an attached property in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are generally that any <xref:System.Windows.DependencyObject> can have an attached property set on them. Therefore, any <xref:System.Windows.DependencyObject> derived class can override the metadata for any attached property, as it might be set on an instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. If the attached property is set on an instance of your class, those override property metadata characteristics apply. For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set.
|
||||
In WPF, attached properties are implemented as dependency properties. This means that they also have property metadata, which individual classes can override. The scoping considerations for an attached property in WPF are generally that any <xref:System.Windows.DependencyObject> can have an attached property set on them. Therefore, any <xref:System.Windows.DependencyObject> derived class can override the metadata for any attached property, as it might be set on an instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting properties. If the attached property is set on an instance of your class, those override property metadata characteristics apply. For instance, you can override the default value, such that your override value is reported as the value of the attached property on instances of your class, whenever the property is not otherwise set.
|
||||
|
||||
> [!NOTE]
|
||||
> The <xref:System.Windows.FrameworkPropertyMetadata.Inherits%2A> property is not relevant for attached properties.
|
||||
|
||||
@@ -12,7 +12,7 @@ helpviewer_keywords:
|
||||
ms.assetid: d10150ec-90c5-4571-8d35-84bafa2429a4
|
||||
---
|
||||
# Dependency Property Security
|
||||
Dependency properties should generally be considered to be public properties. The nature of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system prevents the ability to make security guarantees about a dependency property value.
|
||||
Dependency properties should generally be considered to be public properties. The nature of the Windows Presentation Foundation (WPF) property system prevents the ability to make security guarantees about a dependency property value.
|
||||
|
||||
<a name="AccessSecurity"></a>
|
||||
## Access and Security of Wrappers and Dependency Properties
|
||||
|
||||
@@ -9,19 +9,19 @@ helpviewer_keywords:
|
||||
ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc
|
||||
---
|
||||
# Dependency Property Value Precedence
|
||||
<a name="introduction"></a> This topic explains how the workings of the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] property system can affect the value of a dependency property, and describes the precedence by which aspects of the property system apply to the effective value of a property.
|
||||
<a name="introduction"></a> This topic explains how the workings of the Windows Presentation Foundation (WPF) property system can affect the value of a dependency property, and describes the precedence by which aspects of the property system apply to the effective value of a property.
|
||||
|
||||
<a name="prerequisites"></a>
|
||||
## Prerequisites
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] classes, and have read [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this topic, you should also understand [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and know how to write [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications.
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on WPF classes, and have read [Dependency Properties Overview](dependency-properties-overview.md). To follow the examples in this topic, you should also understand WPF applications.
|
||||
|
||||
<a name="intro"></a>
|
||||
## The WPF Property System
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system offers a powerful way to have the value of dependency properties be determined by a variety of factors, enabling features such as real-time property validation, late binding, and notifying related properties of changes to values for other properties. The exact order and logic that is used to determine dependency property values is reasonably complex. Knowing this order will help you avoid unnecessary property setting, and might also clear up confusion over exactly why some attempt to influence or anticipate a dependency property value did not end up resulting in the value you expected.
|
||||
The WPF property system offers a powerful way to have the value of dependency properties be determined by a variety of factors, enabling features such as real-time property validation, late binding, and notifying related properties of changes to values for other properties. The exact order and logic that is used to determine dependency property values is reasonably complex. Knowing this order will help you avoid unnecessary property setting, and might also clear up confusion over exactly why some attempt to influence or anticipate a dependency property value did not end up resulting in the value you expected.
|
||||
|
||||
<a name="multiple_sets"></a>
|
||||
## Dependency Properties Might Be "Set" in Multiple Places
|
||||
The following is example [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] where the same property (<xref:System.Windows.Controls.Control.Background%2A>) has three different "set" operations that might influence the value.
|
||||
The following is example XAML where the same property (<xref:System.Windows.Controls.Control.Background%2A>) has three different "set" operations that might influence the value.
|
||||
|
||||
:::code language="xaml" source="./snippets/dependency-property-value-precedence/xaml/MainWindow.xaml" id="DependencyPropertyValuePrecedence":::
|
||||
|
||||
@@ -37,13 +37,13 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc
|
||||
|
||||
2. **Active animations, or animations with a Hold behavior.** In order to have any practical effect, an animation of a property must be able to have precedence over the base (unanimated) value, even if that value was set locally. For details, see [Coercion, Animation, and Base Value](#animations) later in this topic.
|
||||
|
||||
3. **Local value.** A local value might be set through the convenience of the "wrapper" property, which also equates to setting as an attribute or property element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], or by a call to the <xref:System.Windows.DependencyObject.SetValue%2A> API using a property of a specific instance. If you set a local value by using a binding or a resource, these each act in the precedence as if a direct value was set.
|
||||
3. **Local value.** A local value might be set through the convenience of the "wrapper" property, which also equates to setting as an attribute or property element in XAML, or by a call to the <xref:System.Windows.DependencyObject.SetValue%2A> API using a property of a specific instance. If you set a local value by using a binding or a resource, these each act in the precedence as if a direct value was set.
|
||||
|
||||
4. **TemplatedParent template properties.** An element has a <xref:System.Windows.FrameworkElement.TemplatedParent%2A> if it was created as part of a template (a <xref:System.Windows.Controls.ControlTemplate> or <xref:System.Windows.DataTemplate>). For details on when this applies, see [TemplatedParent](#templatedparent) later in this topic. Within the template, the following precedence applies:
|
||||
|
||||
1. Triggers from the <xref:System.Windows.FrameworkElement.TemplatedParent%2A> template.
|
||||
|
||||
2. Property sets (typically through [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attributes) in the <xref:System.Windows.FrameworkElement.TemplatedParent%2A> template.
|
||||
2. Property sets (typically through XAML attributes) in the <xref:System.Windows.FrameworkElement.TemplatedParent%2A> template.
|
||||
|
||||
5. **Implicit style.** Applies only to the `Style` property. The `Style` property is filled by any style resource with a key that matches the type of that element. That style resource must exist either in the page or the application; lookup for an implicit style resource does not proceed into the themes.
|
||||
|
||||
@@ -75,13 +75,13 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc
|
||||
|
||||
- **Implicit style.** The <xref:System.Windows.FrameworkElement.Style%2A> property is not set directly. However, the <xref:System.Windows.FrameworkElement.Style%2A> exists at some level in the resource lookup sequence (page, application) and is keyed using a resource key that matches the type the style is to be applied to. In this case, the <xref:System.Windows.FrameworkElement.Style%2A> property itself acts by a precedence identified in the sequence as item 5. This condition can be detected by using <xref:System.Windows.DependencyPropertyHelper> against the <xref:System.Windows.FrameworkElement.Style%2A> property and looking for <xref:System.Windows.BaseValueSource.ImplicitStyleReference> in the results.
|
||||
|
||||
- **Default style**, also known as **theme style.** The <xref:System.Windows.FrameworkElement.Style%2A> property is not set directly, and in fact will read as `null` up until run time. In this case, the style comes from the run-time theme evaluation that is part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] presentation engine.
|
||||
- **Default style**, also known as **theme style.** The <xref:System.Windows.FrameworkElement.Style%2A> property is not set directly, and in fact will read as `null` up until run time. In this case, the style comes from the run-time theme evaluation that is part of the WPF presentation engine.
|
||||
|
||||
For implicit styles not in themes, the type must match exactly - a `MyButton` `Button`-derived class will not implicitly use a style for `Button`.
|
||||
|
||||
<a name="themestyles"></a>
|
||||
## Default (Theme) Styles
|
||||
Every control that ships with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has a default style. That default style potentially varies by theme, which is why this default style is sometimes referred to as a theme style.
|
||||
Every control that ships with WPF has a default style. That default style potentially varies by theme, which is why this default style is sometimes referred to as a theme style.
|
||||
|
||||
The most important information that is found within a default style for a control is its control template, which exists in the theme style as a setter for its <xref:System.Windows.Controls.Control.Template%2A> property. If there were no template from default styles, a control without a custom template as part of a custom style would have no visual appearance at all. The template from the default style gives the visual appearance of each control a basic structure, and also defines the connections between properties defined in the visual tree of the template and the corresponding control class. Each control exposes a set of properties that can influence the visual appearance of the control without completely replacing the template. For example, consider the default visual appearance of a <xref:System.Windows.Controls.Primitives.Thumb> control, which is a component of a <xref:System.Windows.Controls.Primitives.ScrollBar>.
|
||||
|
||||
@@ -109,7 +109,7 @@ ms.assetid: 1fbada8e-4867-4ed1-8d97-62c07dad7ebc
|
||||
|
||||
Multiple animations might be applied to a single property, with each of these animations possibly having been defined from different points in the value precedence. However, these animations will potentially composite their values, rather than just applying the animation from the higher precedence. This depends on exactly how the animations are defined, and the type of the value that is being animated. For more information about animating properties, see [Animation Overview](../graphics-multimedia/animation-overview.md).
|
||||
|
||||
Coercion applies at the highest level of all. Even an already running animation is subject to value coercion. Certain existing dependency properties in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] have built-in coercion. For a custom dependency property, you define the coercion behavior for a custom dependency property by writing a <xref:System.Windows.CoerceValueCallback> and passing the callback as part of metadata when you create the property. You can also override coercion behavior of existing properties by overriding the metadata on that property in a derived class. Coercion interacts with the base value in such a way that the constraints on coercion are applied as those constraints exist at the time, but the base value is still retained. Therefore, if constraints in coercion are later lifted, the coercion will return the closest value possible to that base value, and potentially the coercion influence on a property will cease as soon as all constraints are lifted. For more information about coercion behavior, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md).
|
||||
Coercion applies at the highest level of all. Even an already running animation is subject to value coercion. Certain existing dependency properties in WPF have built-in coercion. For a custom dependency property, you define the coercion behavior for a custom dependency property by writing a <xref:System.Windows.CoerceValueCallback> and passing the callback as part of metadata when you create the property. You can also override coercion behavior of existing properties by overriding the metadata on that property in a derived class. Coercion interacts with the base value in such a way that the constraints on coercion are applied as those constraints exist at the time, but the base value is still retained. Therefore, if constraints in coercion are later lifted, the coercion will return the closest value possible to that base value, and potentially the coercion influence on a property will cease as soon as all constraints are lifted. For more information about coercion behavior, see [Dependency Property Callbacks and Validation](dependency-property-callbacks-and-validation.md).
|
||||
|
||||
<a name="triggers"></a>
|
||||
## Trigger Behaviors
|
||||
|
||||
@@ -9,7 +9,7 @@ helpviewer_keywords:
|
||||
ms.assetid: d0d6df69-daf9-4cf3-b7f9-ffee588037a3
|
||||
---
|
||||
# Digital Ink
|
||||
This section discusses the use of digital ink in the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. Traditionally found only in the Tablet PC SDK, digital ink is now available in the core Windows Presentation Foundation. This means you can now develop full-fledged Tablet PC applications by using the power of Windows Presentation Foundation.
|
||||
This section discusses the use of digital ink in the WPF. Traditionally found only in the Tablet PC SDK, digital ink is now available in the core Windows Presentation Foundation. This means you can now develop full-fledged Tablet PC applications by using the power of Windows Presentation Foundation.
|
||||
|
||||
## In This Section
|
||||
[Overviews](digital-ink-overviews.md)
|
||||
|
||||
@@ -14,11 +14,11 @@ helpviewer_keywords:
|
||||
ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8
|
||||
---
|
||||
# Documents in WPF
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] offers a wide range of document features that enable the creation of high-fidelity content that is designed to be more easily accessed and read than in previous generations of Windows. In addition to enhanced capabilities and quality, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also provides integrated services for document display, packaging, and security. This topic provides an introduction to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] document types and document packaging.
|
||||
WPF also provides integrated services for document display, packaging, and security. This topic provides an introduction to WPF document types and document packaging.
|
||||
|
||||
<a name="types_of_documents"></a>
|
||||
## Types of Documents
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] divides documents into two broad categories based on their intended use; these document categories are termed "fixed documents" and "flow documents."
|
||||
WPF divides documents into two broad categories based on their intended use; these document categories are termed "fixed documents" and "flow documents."
|
||||
|
||||
Fixed documents are intended for applications that require a precise "what you see is what you get" (WYSIWYG) presentation, independent of the display or printer hardware used. Typical uses for fixed documents include desktop publishing, word processing, and form layout, where adherence to the original page design is critical. As part of its layout, a fixed document maintains the precise positional placement of content elements independent of the display or print device in use. For example, a fixed document page viewed on 96 dpi display will appear exactly the same when it is output to a 600 dpi laser printer as when it is output to a 4800 dpi phototypesetter. The page layout remains the same in all cases, while the document quality maximizes to the capabilities of each device.
|
||||
|
||||
@@ -26,10 +26,10 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8
|
||||
|
||||
<a name="document_viewer"></a>
|
||||
## Document Controls and Text Layout
|
||||
The .NET Framework provides a set of pre-built controls that simplify using fixed documents, flow documents, and general text within your application. The display of fixed document content is supported using the <xref:System.Windows.Controls.DocumentViewer> control. Display of flow document content is supported by three different controls: <xref:System.Windows.Controls.FlowDocumentReader>, <xref:System.Windows.Controls.FlowDocumentPageViewer>, and <xref:System.Windows.Controls.FlowDocumentScrollViewer> which map to different user scenarios (see sections below). Other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls provide simplified layout to support general text uses (see [Text in the User Interface](#text_in_the_user_interface), below).
|
||||
The .NET Framework provides a set of pre-built controls that simplify using fixed documents, flow documents, and general text within your application. The display of fixed document content is supported using the <xref:System.Windows.Controls.DocumentViewer> control. Display of flow document content is supported by three different controls: <xref:System.Windows.Controls.FlowDocumentReader>, <xref:System.Windows.Controls.FlowDocumentPageViewer>, and <xref:System.Windows.Controls.FlowDocumentScrollViewer> which map to different user scenarios (see sections below). Other WPF controls provide simplified layout to support general text uses (see [Text in the User Interface](#text_in_the_user_interface), below).
|
||||
|
||||
### Fixed Document Control - DocumentViewer
|
||||
The <xref:System.Windows.Controls.DocumentViewer> control is designed to display <xref:System.Windows.Documents.FixedDocument> content. The <xref:System.Windows.Controls.DocumentViewer> control provides an intuitive user interface that provides built-in support for common operations including print output, copy to clipboard, zoom, and text search features. The control provides access to pages of content through a familiar scrolling mechanism. Like all [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] controls, <xref:System.Windows.Controls.DocumentViewer> supports complete or partial restyling, which enables the control to be visually integrated into virtually any application or environment.
|
||||
The <xref:System.Windows.Controls.DocumentViewer> control is designed to display <xref:System.Windows.Documents.FixedDocument> content. The <xref:System.Windows.Controls.DocumentViewer> control provides an intuitive user interface that provides built-in support for common operations including print output, copy to clipboard, zoom, and text search features. The control provides access to pages of content through a familiar scrolling mechanism. Like all WPF controls, <xref:System.Windows.Controls.DocumentViewer> supports complete or partial restyling, which enables the control to be visually integrated into virtually any application or environment.
|
||||
|
||||
<xref:System.Windows.Controls.DocumentViewer> is designed to display content in a read-only manner; editing or modification of content is not available and is not supported.
|
||||
|
||||
@@ -47,17 +47,17 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8
|
||||
#### FlowDocumentPageViewer and FlowDocumentScrollViewer
|
||||
<xref:System.Windows.Controls.FlowDocumentPageViewer> shows content in page-at-a-time viewing mode, while <xref:System.Windows.Controls.FlowDocumentScrollViewer> shows content in continuous scrolling mode. Both <xref:System.Windows.Controls.FlowDocumentPageViewer> and <xref:System.Windows.Controls.FlowDocumentScrollViewer> are fixed to a particular viewing mode. Compare to <xref:System.Windows.Controls.FlowDocumentReader>, which includes features that enable the user to dynamically choose between various viewing modes (as provided by the <xref:System.Windows.Controls.FlowDocumentReaderViewingMode> enumeration), at the cost of being more resource intensive than <xref:System.Windows.Controls.FlowDocumentPageViewer> or <xref:System.Windows.Controls.FlowDocumentScrollViewer>.
|
||||
|
||||
By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The default [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for <xref:System.Windows.Controls.FlowDocumentScrollViewer> does not include a toolbar; however, the <xref:System.Windows.Controls.FlowDocumentScrollViewer.IsToolBarVisible%2A> property can be used to enable a built-in toolbar.
|
||||
By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The default UI for <xref:System.Windows.Controls.FlowDocumentScrollViewer> does not include a toolbar; however, the <xref:System.Windows.Controls.FlowDocumentScrollViewer.IsToolBarVisible%2A> property can be used to enable a built-in toolbar.
|
||||
|
||||
<a name="text_in_the_user_interface"></a>
|
||||
### Text in the User Interface
|
||||
Besides adding text to documents, text can obviously be used in application UI such as forms. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the <xref:System.Windows.Controls.TextBlock> element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. <xref:System.Windows.Controls.Label> can be used when minimal text support is required. For more information, see [TextBlock Overview](../controls/textblock-overview.md).
|
||||
Besides adding text to documents, text can obviously be used in application UI such as forms. WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the <xref:System.Windows.Controls.TextBlock> element should be used when limited text support is required, such as a brief sentence in a user interface (UI). <xref:System.Windows.Controls.Label> can be used when minimal text support is required. For more information, see [TextBlock Overview](../controls/textblock-overview.md).
|
||||
|
||||
<a name="packaging"></a>
|
||||
## Document Packaging
|
||||
The <xref:System.IO.Packaging> APIs provide an efficient means to organize application data, document content, and related resources in a single container that is simple to access, portable, and easy to distribute. A ZIP file is an example of a <xref:System.IO.Packaging.Package> type capable of holding multiple objects as a single unit. The packaging APIs provide a default <xref:System.IO.Packaging.ZipPackage> implementation designed using an Open Packaging Conventions standard with XML and ZIP file architecture. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs make it simple to create packages, and to store and access objects within them. An object stored in a <xref:System.IO.Packaging.Package> is referred to as a <xref:System.IO.Packaging.PackagePart> ("part"). Packages can also include signed digital certificates that can be used to identify the originator of a part and to validate that the contents of a package have not been modified. Packages also include a <xref:System.IO.Packaging.PackageRelationship> feature that allows additional information to be added to a package or associated with specific parts without actually modifying the content of existing parts. Package services also support Microsoft Windows Rights Management (RM).
|
||||
The <xref:System.IO.Packaging> APIs provide an efficient means to organize application data, document content, and related resources in a single container that is simple to access, portable, and easy to distribute. A ZIP file is an example of a <xref:System.IO.Packaging.Package> type capable of holding multiple objects as a single unit. The packaging APIs provide a default <xref:System.IO.Packaging.ZipPackage> implementation designed using an Open Packaging Conventions standard with XML and ZIP file architecture. The WPF packaging APIs make it simple to create packages, and to store and access objects within them. An object stored in a <xref:System.IO.Packaging.Package> is referred to as a <xref:System.IO.Packaging.PackagePart> ("part"). Packages can also include signed digital certificates that can be used to identify the originator of a part and to validate that the contents of a package have not been modified. Packages also include a <xref:System.IO.Packaging.PackageRelationship> feature that allows additional information to be added to a package or associated with specific parts without actually modifying the content of existing parts. Package services also support Microsoft Windows Rights Management (RM).
|
||||
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Package architecture serves as the foundation for a number of key technologies:
|
||||
The WPF Package architecture serves as the foundation for a number of key technologies:
|
||||
|
||||
- XPS documents conforming to the XML Paper Specification (XPS).
|
||||
|
||||
@@ -65,13 +65,13 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8
|
||||
|
||||
- Custom storage formats for your own application design.
|
||||
|
||||
Based on the packaging APIs, an <xref:System.Windows.Xps.Packaging.XpsDocument> is specifically designed for storing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] fixed content documents. An <xref:System.Windows.Xps.Packaging.XpsDocument> is a self-contained document that can be opened in a viewer, displayed in a <xref:System.Windows.Controls.DocumentViewer> control, routed to a print spool, or output directly to an XPS-compatible printer.
|
||||
Based on the packaging APIs, an <xref:System.Windows.Xps.Packaging.XpsDocument> is specifically designed for storing WPF fixed content documents. An <xref:System.Windows.Xps.Packaging.XpsDocument> is a self-contained document that can be opened in a viewer, displayed in a <xref:System.Windows.Controls.DocumentViewer> control, routed to a print spool, or output directly to an XPS-compatible printer.
|
||||
|
||||
The following sections provide additional information on the <xref:System.IO.Packaging.Package> and <xref:System.Windows.Xps.Packaging.XpsDocument> APIs provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
|
||||
The following sections provide additional information on the <xref:System.IO.Packaging.Package> and <xref:System.Windows.Xps.Packaging.XpsDocument> APIs provided with WPF.
|
||||
|
||||
<a name="packages"></a>
|
||||
### Package Components
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs allow application data and documents to be organized into a single portable unit. A ZIP file is one of the most common types of packages and is the default package type provided with [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. <xref:System.IO.Packaging.Package> itself is an abstract class from which <xref:System.IO.Packaging.ZipPackage> is implemented using an open standard XML and ZIP file architecture. The <xref:System.IO.Packaging.Package.Open%2A> method uses <xref:System.IO.Packaging.ZipPackage> to create and use ZIP files by default. A package can contain three basic types of items:
|
||||
The WPF packaging APIs allow application data and documents to be organized into a single portable unit. A ZIP file is one of the most common types of packages and is the default package type provided with WPF. <xref:System.IO.Packaging.Package> itself is an abstract class from which <xref:System.IO.Packaging.ZipPackage> is implemented using an open standard XML and ZIP file architecture. The <xref:System.IO.Packaging.Package.Open%2A> method uses <xref:System.IO.Packaging.ZipPackage> to create and use ZIP files by default. A package can contain three basic types of items:
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
@@ -81,7 +81,7 @@ ms.assetid: 6e8db7bc-050a-4070-aa72-bb8c46e87ff8
|
||||
|
||||
<a name="PackageParts"></a>
|
||||
#### PackageParts
|
||||
A <xref:System.IO.Packaging.PackagePart> ("part") is an abstract class that refers to an object stored in a <xref:System.IO.Packaging.Package>. In a ZIP file, the package parts correspond to the individual files stored within the ZIP file. <xref:System.IO.Packaging.ZipPackagePart> provides the default implementation for serializable objects stored in a <xref:System.IO.Packaging.ZipPackage>. Like a file system, parts contained in the package are stored in hierarchical directory or "folder-style" organization. Using the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] packaging APIs, applications can write, store, and read multiple <xref:System.IO.Packaging.PackagePart> objects using a single ZIP file container.
|
||||
A <xref:System.IO.Packaging.PackagePart> ("part") is an abstract class that refers to an object stored in a <xref:System.IO.Packaging.Package>. In a ZIP file, the package parts correspond to the individual files stored within the ZIP file. <xref:System.IO.Packaging.ZipPackagePart> provides the default implementation for serializable objects stored in a <xref:System.IO.Packaging.ZipPackage>. Like a file system, parts contained in the package are stored in hierarchical directory or "folder-style" organization. Using the WPF packaging APIs, applications can write, store, and read multiple <xref:System.IO.Packaging.PackagePart> objects using a single ZIP file container.
|
||||
|
||||
<a name="PackageDigitalSignatures"></a>
|
||||
#### PackageDigitalSignatures
|
||||
|
||||
@@ -10,7 +10,7 @@ ms.assetid: 7bf37ccb-5d09-4eae-9661-929582aeb259
|
||||
---
|
||||
# Documents
|
||||
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a versatile set of components that enable developers to build applications with advanced document features and an improved reading experience. In addition to enhanced capabilities and quality, [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] also provides simplified management services for document packaging, security, and storage.
|
||||
Windows Presentation Foundation (WPF) provides a versatile set of components that enable developers to build applications with advanced document features and an improved reading experience. In addition to enhanced capabilities and quality, Windows Presentation Foundation (WPF) also provides simplified management services for document packaging, security, and storage.
|
||||
|
||||
## In This Section
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 559c0804-c62a-4640-b6b9-cbd2aa9fb99c
|
||||
---
|
||||
# Drag and Drop How-to Topics
|
||||
The following examples demonstrate how to accomplish common tasks using the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] drag-and-drop framework.
|
||||
The following examples demonstrate how to accomplish common tasks using the Windows Presentation Foundation (WPF) drag-and-drop framework.
|
||||
|
||||
## In This Section
|
||||
[Open a File That is Dropped on a RichTextBox Control](how-to-open-a-file-that-is-dropped-on-a-richtextbox-control.md)
|
||||
|
||||
@@ -16,7 +16,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 1a5b27b0-0ac5-4cdf-86c0-86ac0271fa64
|
||||
---
|
||||
# Drag and Drop Overview
|
||||
This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications. Drag-and-drop commonly refers to a method of data transfer that involves using a mouse (or some other pointing device) to select one or more objects, dragging these objects over some desired drop target in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], and dropping them.
|
||||
This topic provides an overview of drag-and-drop support in user interface (UI), and dropping them.
|
||||
|
||||
<a name="Drag_and_Drop_Support"></a>
|
||||
## Drag-and-Drop Support in WPF
|
||||
@@ -26,9 +26,9 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi
|
||||
|
||||
The particular actions performed during a drag-and-drop operation are application specific, and often determined by context. For example, dragging a selection of files from one folder to another on the same storage device moves the files by default, whereas dragging files from a Universal Naming Convention (UNC) share to a local folder copies the files by default.
|
||||
|
||||
The drag-and-drop facilities provided by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single application, or between different applications. Dragging-and-dropping between [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications and other Windows applications is also fully supported.
|
||||
The drag-and-drop facilities provided by WPF are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single application, or between different applications. Dragging-and-dropping between WPF applications and other Windows applications is also fully supported.
|
||||
|
||||
In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], any <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the <xref:System.Windows.DragDrop> class. The <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> classes contain aliases for the <xref:System.Windows.DragDrop> attached events so that the events appear in the class members list when a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> is inherited as a base element. Event handlers that are attached to these events are attached to the underlying <xref:System.Windows.DragDrop> attached event and receive the same event data instance. For more information, see the <xref:System.Windows.UIElement.Drop?displayProperty=nameWithType> event.
|
||||
In WPF, any <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the <xref:System.Windows.DragDrop> class. The <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> classes contain aliases for the <xref:System.Windows.DragDrop> attached events so that the events appear in the class members list when a <xref:System.Windows.UIElement> or <xref:System.Windows.ContentElement> is inherited as a base element. Event handlers that are attached to these events are attached to the underlying <xref:System.Windows.DragDrop> attached event and receive the same event data instance. For more information, see the <xref:System.Windows.UIElement.Drop?displayProperty=nameWithType> event.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> OLE drag-and-drop does not work while in the Internet zone.
|
||||
@@ -50,9 +50,9 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi
|
||||
The source and target of a drag-and-drop operation are UI elements; however, the data that is actually being transferred typically does not have a visual representation. You can write code to provide a visual representation of the data that is dragged, such as occurs when dragging files in Windows Explorer. By default, feedback is provided to the user by changing the cursor to represent the effect that the drag-and-drop operation will have on the data, such as whether the data will be moved or copied.
|
||||
|
||||
### Drag-and-Drop Effects
|
||||
Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data or you can move the data. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] defines a <xref:System.Windows.DragDropEffects> enumeration that you can use to specify the effect of a drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the <xref:System.Windows.DragDrop.DoDragDrop%2A> method. In the drop target, you can specify the effect that the target intends in the <xref:System.Windows.DragEventArgs.Effects%2A> property of the <xref:System.Windows.DragEventArgs> class. When the drop target specifies its intended effect in the <xref:System.Windows.DragDrop.DragOver> event, that information is passed back to the drag source in the <xref:System.Windows.DragDrop.GiveFeedback> event. The drag source uses this information to inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target specifies its actual effect in the <xref:System.Windows.DragDrop.Drop> event. That information is passed back to the drag source as the return value of the <xref:System.Windows.DragDrop.DoDragDrop%2A> method. If the drop target returns an effect that is not in the drag sources list of `allowedEffects`, the drag-and-drop operation is cancelled without any data transfer occurring.
|
||||
Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data or you can move the data. WPF defines a <xref:System.Windows.DragDropEffects> enumeration that you can use to specify the effect of a drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the <xref:System.Windows.DragDrop.DoDragDrop%2A> method. In the drop target, you can specify the effect that the target intends in the <xref:System.Windows.DragEventArgs.Effects%2A> property of the <xref:System.Windows.DragEventArgs> class. When the drop target specifies its intended effect in the <xref:System.Windows.DragDrop.DragOver> event, that information is passed back to the drag source in the <xref:System.Windows.DragDrop.GiveFeedback> event. The drag source uses this information to inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target specifies its actual effect in the <xref:System.Windows.DragDrop.Drop> event. That information is passed back to the drag source as the return value of the <xref:System.Windows.DragDrop.DoDragDrop%2A> method. If the drop target returns an effect that is not in the drag sources list of `allowedEffects`, the drag-and-drop operation is cancelled without any data transfer occurring.
|
||||
|
||||
It is important to remember that in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the <xref:System.Windows.DragDropEffects> values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application.
|
||||
It is important to remember that in WPF, the <xref:System.Windows.DragDropEffects> values are only used to provide communication between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual effect of the drag-and-drop operation depends on you to write the appropriate code in your application.
|
||||
|
||||
For example, the drop target might specify that the effect of dropping data on it is to move the data. However, to move the data, it must be both added to the target element and removed from the source element. The source element might indicate that it allows moving the data, but if you do not provide the code to remove the data from the source element, the end result will be that the data is copied, and not moved.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 77c48920-8c8b-41eb-8fe8-b411962c8623
|
||||
---
|
||||
# Drag and Drop
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a highly flexible drag and drop infrastructure which supports dragging and dropping of data within both [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications as well as other Windows applications.
|
||||
WPF applications as well as other Windows applications.
|
||||
|
||||
## In This Section
|
||||
[Drag and Drop Overview](drag-and-drop-overview.md)
|
||||
|
||||
@@ -8,14 +8,14 @@ helpviewer_keywords:
|
||||
ms.assetid: 587ab17e-a419-4ad5-b6da-8933a8e83d97
|
||||
---
|
||||
# Draw Text Using Glyphs
|
||||
This topic explains how to use the low-level <xref:System.Windows.Documents.Glyphs> object to display text in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
|
||||
This topic explains how to use the low-level <xref:System.Windows.Documents.Glyphs> object to display text in Extensible Application Markup Language (XAML).
|
||||
|
||||
## Example
|
||||
The following examples show how to define properties for a <xref:System.Windows.Documents.Glyphs> object in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The <xref:System.Windows.Documents.Glyphs> object represents the output of a <xref:System.Windows.Media.GlyphRun> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the local computer.
|
||||
The following examples show how to define properties for a <xref:System.Windows.Documents.Glyphs> object in XAML. The examples assume that the Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the local computer.
|
||||
|
||||
[!code-xaml[GlyphsOvwSample1#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSample1/CS/default.xaml#1)]
|
||||
|
||||
This example shows how to define other properties of <xref:System.Windows.Documents.Glyphs> objects in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
|
||||
This example shows how to define other properties of <xref:System.Windows.Documents.Glyphs> objects in XAML.
|
||||
|
||||
[!code-xaml[GlyphsOvwSamp2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSamp2/CS/default.xaml#1)]
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ ms.assetid: b1d851c1-331c-4814-9964-6fe769db6f1f
|
||||
---
|
||||
# Drawing Formatted Text
|
||||
|
||||
This topic provides an overview of the features of the <xref:System.Windows.Media.FormattedText> object. This object provides low-level control for drawing text in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications.
|
||||
This topic provides an overview of the features of the <xref:System.Windows.Media.FormattedText> object. This object provides low-level control for drawing text in Windows Presentation Foundation (WPF) applications.
|
||||
|
||||
## Technology Overview
|
||||
|
||||
@@ -22,13 +22,13 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
|
||||

|
||||
|
||||
> [!NOTE]
|
||||
> For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|
||||
> For those developers migrating from the Win32 API, the table in the [Win32 Migration](#win32_migration) section lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF).
|
||||
|
||||
### Reasons for Using Formatted Text
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the <xref:System.Windows.Controls.TextBlock> element should be used when limited text support is required, such as a brief sentence in a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. <xref:System.Windows.Controls.Label> can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md).
|
||||
WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own list of features and limitations. In general, the <xref:System.Windows.Controls.TextBlock> element should be used when limited text support is required, such as a brief sentence in a user interface (UI). <xref:System.Windows.Controls.Label> can be used when minimal text support is required. For more information, see [Documents in WPF](documents-in-wpf.md).
|
||||
|
||||
The <xref:System.Windows.Media.FormattedText> object provides greater text formatting features than [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section [Converting Formatted Text to a Geometry](#converting_formatted_text).
|
||||
The <xref:System.Windows.Media.FormattedText> object provides greater text formatting features than Windows Presentation Foundation (WPF) text controls, and can be useful in cases where you want to use text as a decorative element. For more information, see the following section [Converting Formatted Text to a Geometry](#converting_formatted_text).
|
||||
|
||||
In addition, the <xref:System.Windows.Media.FormattedText> object is useful for creating text-oriented <xref:System.Windows.Media.DrawingVisual>-derived objects. <xref:System.Windows.Media.DrawingVisual> is a lightweight drawing class that is used to render shapes, images, or text. For more information, see [Hit Test Using DrawingVisuals Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Visual%20Layer/DrawingVisual).
|
||||
|
||||
@@ -49,7 +49,7 @@ This topic provides an overview of the features of the <xref:System.Windows.Medi
|
||||
|
||||
### Font Size Unit of Measure
|
||||
|
||||
As with other text objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, the <xref:System.Windows.Media.FormattedText> object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion.
|
||||
As with other text objects in Windows Presentation Foundation (WPF) applications, the <xref:System.Windows.Media.FormattedText> object uses device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of measure. If you want to use display text in units of points in Windows Presentation Foundation (WPF) applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code example shows how to perform this conversion.
|
||||
|
||||
[!code-csharp[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/csharp/VS_Snippets_Wpf/FormattedTextSnippets/CSharp/Window1.xaml.cs#formattedtextsnippets2)]
|
||||
[!code-vb[FormattedTextSnippets#FormattedTextSnippets2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FormattedTextSnippets/visualbasic/window1.xaml.vb#formattedtextsnippets2)]
|
||||
@@ -89,7 +89,7 @@ Sphere following the path geometry of text
|
||||
|
||||
## Win32 Migration
|
||||
|
||||
The features of <xref:System.Windows.Media.FormattedText> for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|
||||
The features of <xref:System.Windows.Media.FormattedText> for drawing text are similar to the features of the Win32 DrawText function. For those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the approximate equivalent in Windows Presentation Foundation (WPF).
|
||||
|
||||
|DrawText flag|WPF equivalent|Notes|
|
||||
|-------------------|--------------------|-----------|
|
||||
|
||||
@@ -11,7 +11,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 7324f243-03af-4c2b-b0db-26ac6cdfcbe4
|
||||
---
|
||||
# DynamicResource Markup Extension
|
||||
Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] property attribute by deferring that value to be a reference to a defined resource. Lookup behavior for that resource is analogous to run-time lookup.
|
||||
Provides a value for any XAML property attribute by deferring that value to be a reference to a defined resource. Lookup behavior for that resource is analogous to run-time lookup.
|
||||
|
||||
## XAML Attribute Usage
|
||||
|
||||
@@ -36,7 +36,7 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla
|
||||
|`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive) if a resource was created in markup, or was provided as the `key` parameter when calling <xref:System.Windows.ResourceDictionary.Add%2A?displayProperty=nameWithType> if the resource was created in code.|
|
||||
|
||||
## Remarks
|
||||
A `DynamicResource` will create a temporary expression during the initial compilation and thus defer lookup for resources until the requested resource value is actually required in order to construct an object. This may potentially be after the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is loaded. The resource value will be found based on key search against all active resource dictionaries starting from the current page scope, and is substituted for the placeholder expression from compilation.
|
||||
A `DynamicResource` will create a temporary expression during the initial compilation and thus defer lookup for resources until the requested resource value is actually required in order to construct an object. This may potentially be after the XAML page is loaded. The resource value will be found based on key search against all active resource dictionaries starting from the current page scope, and is substituted for the placeholder expression from compilation.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> In terms of dependency property precedence, a `DynamicResource` expression is equivalent to the position where the dynamic resource reference is applied. If you set a local value for a property that previously had a `DynamicResource` expression as the local value, the `DynamicResource` is completely removed. For details, see [Dependency Property Value Precedence](dependency-property-value-precedence.md).
|
||||
@@ -63,9 +63,9 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla
|
||||
|
||||
The verbose usage is often useful for extensions that have more than one settable property, or if some properties are optional. Because `DynamicResource` has only one settable property, which is required, this verbose usage is not typical.
|
||||
|
||||
In the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor implementation, the handling for this markup extension is defined by the <xref:System.Windows.DynamicResourceExtension> class.
|
||||
In the WPF XAML processor implementation, the handling for this markup extension is defined by the <xref:System.Windows.DynamicResourceExtension> class.
|
||||
|
||||
`DynamicResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] use the { and } characters in their attribute syntax, which is the convention by which a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
`DynamicResource` is a markup extension. Markup extensions are typically implemented when there is a requirement to escape attribute values to be other than literal values or handler names, and the requirement is more global than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup extension must process the attribute. For more information, see [Markup Extensions and WPF XAML](markup-extensions-and-wpf-xaml.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ helpviewer_keywords:
|
||||
ms.assetid: d3b93c6f-aa6b-486d-a010-d097ea8a516b
|
||||
---
|
||||
# Events (WPF)
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] introduces routed events that can invoke handlers that exist on various listeners in the element tree of an application.
|
||||
Windows Presentation Foundation (WPF) introduces routed events that can invoke handlers that exist on various listeners in the element tree of an application.
|
||||
|
||||
## In This Section
|
||||
[Routed Events Overview](routed-events-overview.md)
|
||||
|
||||
@@ -12,7 +12,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 0230c4eb-0c8a-462b-ac4b-ae3e511659f4
|
||||
---
|
||||
# Focus Overview
|
||||
In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus. These concepts are discussed in detail in this overview. Understanding the difference in these concepts is important for creating complex applications that have multiple regions where focus can be obtained.
|
||||
In WPF there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus. These concepts are discussed in detail in this overview. Understanding the difference in these concepts is important for creating complex applications that have multiple regions where focus can be obtained.
|
||||
|
||||
The major classes that participate in focus management are the <xref:System.Windows.Input.Keyboard> class, the <xref:System.Windows.Input.FocusManager> class, and the base element classes, such as <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>. For more information about the base elements, see the [Base Elements Overview](base-elements-overview.md).
|
||||
|
||||
@@ -20,11 +20,11 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)
|
||||
|
||||
<a name="Keyboard_Focus"></a>
|
||||
## Keyboard Focus
|
||||
Keyboard focus refers to the element that is currently receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the element that has keyboard focus will have <xref:System.Windows.IInputElement.IsKeyboardFocused%2A> set to `true`. The static property <xref:System.Windows.Input.Keyboard.FocusedElement%2A> on the <xref:System.Windows.Input.Keyboard> class gets the element that currently has keyboard focus.
|
||||
Keyboard focus refers to the element that is currently receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have <xref:System.Windows.IInputElement.IsKeyboardFocused%2A> set to `true`. The static property <xref:System.Windows.Input.Keyboard.FocusedElement%2A> on the <xref:System.Windows.Input.Keyboard> class gets the element that currently has keyboard focus.
|
||||
|
||||
In order for an element to obtain keyboard focus, the <xref:System.Windows.UIElement.Focusable%2A> and the <xref:System.Windows.UIElement.IsVisible%2A> properties on the base elements must be set to `true`. Some classes, such as the <xref:System.Windows.Controls.Panel> base class, have <xref:System.Windows.UIElement.Focusable%2A> set to `false` by default; therefore, you must set <xref:System.Windows.UIElement.Focusable%2A> to `true` if you want such an element to be able to obtain keyboard focus.
|
||||
|
||||
Keyboard focus can be obtained through user interaction with the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], such as tabbing to an element or clicking the mouse on certain elements. Keyboard focus can also be obtained programmatically by using the <xref:System.Windows.Input.Keyboard.Focus%2A> method on the <xref:System.Windows.Input.Keyboard> class. The <xref:System.Windows.Input.Keyboard.Focus%2A> method attempts to give the specified element keyboard focus. The returned element is the element that has keyboard focus, which might be a different element than requested if either the old or new focus object block the request.
|
||||
Keyboard focus can be obtained through user interaction with the UI, such as tabbing to an element or clicking the mouse on certain elements. Keyboard focus can also be obtained programmatically by using the <xref:System.Windows.Input.Keyboard.Focus%2A> method on the <xref:System.Windows.Input.Keyboard> class. The <xref:System.Windows.Input.Keyboard.Focus%2A> method attempts to give the specified element keyboard focus. The returned element is the element that has keyboard focus, which might be a different element than requested if either the old or new focus object block the request.
|
||||
|
||||
The following example uses the <xref:System.Windows.Input.Keyboard.Focus%2A> method to set keyboard focus on a <xref:System.Windows.Controls.Button>.
|
||||
|
||||
@@ -43,7 +43,7 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)
|
||||
|
||||
An element that has keyboard focus has logical focus for the focus scope it belongs to.
|
||||
|
||||
An element can be turned into a focus scope in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] by setting the <xref:System.Windows.Input.FocusManager> attached property <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> to `true`. In code, an element can be turned into a focus scope by calling <xref:System.Windows.Input.FocusManager.SetIsFocusScope%2A>.
|
||||
An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the <xref:System.Windows.Input.FocusManager> attached property <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> to `true`. In code, an element can be turned into a focus scope by calling <xref:System.Windows.Input.FocusManager.SetIsFocusScope%2A>.
|
||||
|
||||
The following example makes a <xref:System.Windows.Controls.StackPanel> into a focus scope by setting the <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> attached property.
|
||||
|
||||
@@ -54,7 +54,7 @@ In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)
|
||||
|
||||
<xref:System.Windows.Input.FocusManager.GetFocusScope%2A> returns the focus scope for the specified element.
|
||||
|
||||
Classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] which are focus scopes by default are <xref:System.Windows.Window>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Controls.ToolBar>, and <xref:System.Windows.Controls.ContextMenu>.
|
||||
Classes in WPF which are focus scopes by default are <xref:System.Windows.Window>, <xref:System.Windows.Controls.MenuItem>, <xref:System.Windows.Controls.ToolBar>, and <xref:System.Windows.Controls.ContextMenu>.
|
||||
|
||||
<xref:System.Windows.Input.FocusManager.GetFocusedElement%2A> gets the focused element for the specified focus scope. <xref:System.Windows.Input.FocusManager.SetFocusedElement%2A> sets the focused element in the specified focus scope. <xref:System.Windows.Input.FocusManager.SetFocusedElement%2A> is typically used to set the initial focused element.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ helpviewer_keywords:
|
||||
ms.assetid: b4a97c97-7f88-4a89-b1d1-cf2c0d087955
|
||||
---
|
||||
# Fonts How-to Topics
|
||||
The topics in this section demonstrate how to use the font features included with [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)].
|
||||
The topics in this section demonstrate how to use the font features included with Windows Presentation Foundation (WPF).
|
||||
|
||||
## In This Section
|
||||
[Enumerate System Fonts](how-to-enumerate-system-fonts.md)
|
||||
|
||||
@@ -8,7 +8,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 6c766a95-ad03-475e-a36f-2243e9495941
|
||||
---
|
||||
# Fonts (WPF)
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] includes support for rich presentation of text using OpenType fonts. A sample pack of OpenType fonts is included with the Windows SDK.
|
||||
Windows Presentation Foundation (WPF) includes support for rich presentation of text using OpenType fonts. A sample pack of OpenType fonts is included with the Windows SDK.
|
||||
|
||||
## In This Section
|
||||
[OpenType Font Features](opentype-font-features.md)
|
||||
|
||||
+1
-1
@@ -40,7 +40,7 @@ HRESULT ForwardTranslateAccelerator(
|
||||
|
||||
In the .NET Framework 4 and later: PresentationHost_v0400.dll
|
||||
|
||||
**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)]
|
||||
**.NET Framework Version:** Available since 3.0
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -7,11 +7,11 @@ helpviewer_keywords:
|
||||
ms.assetid: 9962f380-b885-4b61-a62e-457397083fea
|
||||
---
|
||||
# Framework Property Metadata
|
||||
Framework property metadata options are reported for the properties of object elements considered to be at the WPF framework level in the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] architecture. In general the WPF framework-level designation entails that features such as rendering, data binding, and property system refinements are handled by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] presentation APIs and executables. Framework property metadata is queried by these systems to determine feature-specific characteristics of particular element properties.
|
||||
Framework property metadata options are reported for the properties of object elements considered to be at the WPF framework level in the WPF presentation APIs and executables. Framework property metadata is queried by these systems to determine feature-specific characteristics of particular element properties.
|
||||
|
||||
<a name="prerequisites"></a>
|
||||
## Prerequisites
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). You should also have read [Dependency Property Metadata](dependency-property-metadata.md).
|
||||
This topic assumes that you understand dependency properties from the perspective of a consumer of existing dependency properties on Windows Presentation Foundation (WPF) classes, and have read the [Dependency Properties Overview](dependency-properties-overview.md). You should also have read [Dependency Property Metadata](dependency-property-metadata.md).
|
||||
|
||||
<a name="What_Is_Communicated_by_Framework_Property"></a>
|
||||
## What Is Communicated by Framework Property Metadata
|
||||
@@ -24,11 +24,11 @@ Framework property metadata options are reported for the properties of object el
|
||||
- <xref:System.Windows.FrameworkPropertyMetadata.Inherits%2A>. By default, dependency properties do not inherit values. <xref:System.Windows.FrameworkPropertyMetadata.OverridesInheritanceBehavior%2A> allows the pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing scenarios.
|
||||
|
||||
> [!NOTE]
|
||||
> The term "inherits" in the context of property values means something specific for dependency properties; it means that child elements can inherit the actual dependency property value from parent elements because of a WPF framework-level capability of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] property system. It has nothing to do directly with managed code type and members inheritance through derived types. For details, see [Property Value Inheritance](property-value-inheritance.md).
|
||||
> The term "inherits" in the context of property values means something specific for dependency properties; it means that child elements can inherit the actual dependency property value from parent elements because of a WPF framework-level capability of the WPF property system. It has nothing to do directly with managed code type and members inheritance through derived types. For details, see [Property Value Inheritance](property-value-inheritance.md).
|
||||
|
||||
- Reporting data binding characteristics (<xref:System.Windows.FrameworkPropertyMetadata.IsNotDataBindable%2A>, <xref:System.Windows.FrameworkPropertyMetadata.BindsTwoWayByDefault%2A>). By default, dependency properties in the framework support data binding, with a one-way binding behavior. You might disable data binding if there were no scenario for it whatsoever (because they are intended to be flexible and extensible, there aren't many examples of such properties in the default [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs). You might set binding to have a two-way default for properties that tie together a control's behaviors amongst its component pieces (<xref:System.Windows.Controls.MenuItem.IsSubmenuOpen%2A> is an example) or where two-way binding is the common and expected scenario for users (<xref:System.Windows.Controls.TextBox.Text%2A> is an example). Changing the data binding–related metadata only influences the default; on a per-binding basis that default can always be changed. For details on the binding modes and binding in general, see [Data Binding Overview](../data/data-binding-overview.md).
|
||||
- Reporting data binding characteristics (<xref:System.Windows.FrameworkPropertyMetadata.IsNotDataBindable%2A>, <xref:System.Windows.FrameworkPropertyMetadata.BindsTwoWayByDefault%2A>). By default, dependency properties in the framework support data binding, with a one-way binding behavior. You might disable data binding if there were no scenario for it whatsoever (because they are intended to be flexible and extensible, there aren't many examples of such properties in the default WPF APIs). You might set binding to have a two-way default for properties that tie together a control's behaviors amongst its component pieces (<xref:System.Windows.Controls.MenuItem.IsSubmenuOpen%2A> is an example) or where two-way binding is the common and expected scenario for users (<xref:System.Windows.Controls.TextBox.Text%2A> is an example). Changing the data binding–related metadata only influences the default; on a per-binding basis that default can always be changed. For details on the binding modes and binding in general, see [Data Binding Overview](../data/data-binding-overview.md).
|
||||
|
||||
- Reporting whether properties should be journaled by applications or services that support journaling (<xref:System.Windows.FrameworkPropertyMetadata.Journal%2A>). For general elements, journaling is not enabled by default, but it is selectively enabled for certain user input controls. This property is intended to be read by journaling services including the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of journaling, and is typically set on user controls such as user selections within lists that should be persisted across navigation steps. For information about the journal, see [Navigation Overview](../app-development/navigation-overview.md).
|
||||
- Reporting whether properties should be journaled by applications or services that support journaling (<xref:System.Windows.FrameworkPropertyMetadata.Journal%2A>). For general elements, journaling is not enabled by default, but it is selectively enabled for certain user input controls. This property is intended to be read by journaling services including the WPF implementation of journaling, and is typically set on user controls such as user selections within lists that should be persisted across navigation steps. For information about the journal, see [Navigation Overview](../app-development/navigation-overview.md).
|
||||
|
||||
<a name="Reading_FrameworkPropertyMetadata"></a>
|
||||
## Reading FrameworkPropertyMetadata
|
||||
@@ -36,7 +36,7 @@ Framework property metadata options are reported for the properties of object el
|
||||
|
||||
<a name="Specifying_Metadata"></a>
|
||||
## Specifying Metadata
|
||||
When you create a new metadata instance for purposes of applying metadata to a new dependency property registration, you have the choice of which metadata class to use: the base <xref:System.Windows.PropertyMetadata> or some derived class such as <xref:System.Windows.FrameworkPropertyMetadata>. In general, you should use <xref:System.Windows.FrameworkPropertyMetadata>, particularly if your property has any interaction with property system and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] functions such as layout and data binding. Another option for more sophisticated scenarios is to derive from <xref:System.Windows.FrameworkPropertyMetadata> to create your own metadata reporting class with extra information carried in its members. Or you might use <xref:System.Windows.PropertyMetadata> or <xref:System.Windows.UIPropertyMetadata> to communicate the degree of support for features of your implementation.
|
||||
When you create a new metadata instance for purposes of applying metadata to a new dependency property registration, you have the choice of which metadata class to use: the base <xref:System.Windows.PropertyMetadata> or some derived class such as <xref:System.Windows.FrameworkPropertyMetadata>. In general, you should use <xref:System.Windows.FrameworkPropertyMetadata>, particularly if your property has any interaction with property system and WPF functions such as layout and data binding. Another option for more sophisticated scenarios is to derive from <xref:System.Windows.FrameworkPropertyMetadata> to create your own metadata reporting class with extra information carried in its members. Or you might use <xref:System.Windows.PropertyMetadata> or <xref:System.Windows.UIPropertyMetadata> to communicate the degree of support for features of your implementation.
|
||||
|
||||
For existing properties (<xref:System.Windows.DependencyProperty.AddOwner%2A> or <xref:System.Windows.DependencyProperty.OverrideMetadata%2A> call), you should always override with the metadata type used by the original registration.
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ A <xref:System.Windows.Freezable> is a special type of object that has two state
|
||||
|
||||
A <xref:System.Windows.Freezable> provides a <xref:System.Windows.Freezable.Changed> event to notify observers of any modifications to the object. Freezing a <xref:System.Windows.Freezable> can improve its performance, because it no longer needs to spend resources on change notifications. A frozen <xref:System.Windows.Freezable> can also be shared across threads, while an unfrozen <xref:System.Windows.Freezable> cannot.
|
||||
|
||||
Although the <xref:System.Windows.Freezable> class has many applications, most <xref:System.Windows.Freezable> objects in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] are related to the graphics sub-system.
|
||||
Although the <xref:System.Windows.Freezable> class has many applications, most <xref:System.Windows.Freezable> objects in Windows Presentation Foundation (WPF) are related to the graphics sub-system.
|
||||
|
||||
The <xref:System.Windows.Freezable> class makes it easier to use certain graphics system objects and can help improve application performance. Examples of types that inherit from <xref:System.Windows.Freezable> include the <xref:System.Windows.Media.Brush>, <xref:System.Windows.Media.Transform>, and <xref:System.Windows.Media.Geometry> classes. Because they contain unmanaged resources, the system must monitor these objects for modifications, and then update their corresponding unmanaged resources when there is a change to the original object. Even if you don't actually modify a graphics system object, the system must still spend some of its resources monitoring the object, in case you do change it.
|
||||
|
||||
@@ -32,7 +32,7 @@ For example, suppose you create a <xref:System.Windows.Media.SolidColorBrush> br
|
||||
[!code-csharp[freezablesample_procedural#FrozenExamplePart1](~/samples/snippets/csharp/VS_Snippets_Wpf/freezablesample_procedural/CSharp/freezablesample.cs#frozenexamplepart1)]
|
||||
[!code-vb[freezablesample_procedural#FrozenExamplePart1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/freezablesample_procedural/visualbasic/freezablesample.vb#frozenexamplepart1)]
|
||||
|
||||
When the button is rendered, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] graphics sub-system uses the information you provided to paint a group of pixels to create the appearance of a button. Although you used a solid color brush to describe how the button should be painted, your solid color brush doesn't actually do the painting. The graphics system generates fast, low-level objects for the button and the brush, and it is those objects that actually appear on the screen.
|
||||
When the button is rendered, the WPF graphics sub-system uses the information you provided to paint a group of pixels to create the appearance of a button. Although you used a solid color brush to describe how the button should be painted, your solid color brush doesn't actually do the painting. The graphics system generates fast, low-level objects for the button and the brush, and it is those objects that actually appear on the screen.
|
||||
|
||||
If you were to modify the brush, those low-level objects would have to be regenerated. The freezable class is what gives a brush the ability to find its corresponding generated, low-level objects and to update them when it changes. When this ability is enabled, the brush is said to be "unfrozen."
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ helpviewer_keywords:
|
||||
ms.assetid: e96f9764-4e3f-4d1c-bf20-3fb890118aae
|
||||
---
|
||||
# Globalization and Localization
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides extensive support for the development of world-ready applications.
|
||||
Windows Presentation Foundation (WPF) provides extensive support for the development of world-ready applications.
|
||||
|
||||
## In This Section
|
||||
[WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md)
|
||||
|
||||
@@ -9,11 +9,11 @@ helpviewer_keywords:
|
||||
ms.assetid: 4571ccfe-8a60-4f06-9b37-7ac0b1c2d10f
|
||||
---
|
||||
# Globalization for WPF
|
||||
This topic introduces issues that you should be aware of when writing [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications for the global market. The globalization programming elements are defined in .NET in the <xref:System.Globalization> namespace.
|
||||
This topic introduces issues that you should be aware of when writing Windows Presentation Foundation (WPF) applications for the global market. The globalization programming elements are defined in .NET in the <xref:System.Globalization> namespace.
|
||||
|
||||
<a name="xaml_globalization"></a>
|
||||
## XAML Globalization
|
||||
Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization support defined in the XML specification. The following sections describe some [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] features that you should be aware of.
|
||||
Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization support defined in the XML specification. The following sections describe some XAML features that you should be aware of.
|
||||
|
||||
<a name="char_reference"></a>
|
||||
### Character References
|
||||
@@ -31,7 +31,7 @@ The following example shows a hexadecimal character reference. Notice that it ha
|
||||
|
||||
<a name="encoding"></a>
|
||||
### Encoding
|
||||
The encoding supported by [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] are ASCII, Unicode UTF-16, and UTF-8. The encoding statement is at the beginning of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] document. If no encoding attribute exists and there is no byte-order, the parser defaults to UTF-8. UTF-8 and UTF-16 are the preferred encodings. UTF-7 is not supported. The following example demonstrates how to specify a UTF-8 encoding in a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file.
|
||||
The encoding supported by XAML are ASCII, Unicode UTF-16, and UTF-8. The encoding statement is at the beginning of XAML document. If no encoding attribute exists and there is no byte-order, the parser defaults to UTF-8. UTF-8 and UTF-16 are the preferred encodings. UTF-7 is not supported. The following example demonstrates how to specify a UTF-8 encoding in a XAML file.
|
||||
|
||||
```xaml
|
||||
?xml encoding="UTF-8"?
|
||||
@@ -39,11 +39,11 @@ The following example shows a hexadecimal character reference. Notice that it ha
|
||||
|
||||
<a name="lang_attrib"></a>
|
||||
### Language Attribute
|
||||
[!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] uses [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) to represent the language attribute of an element. To take advantage of the <xref:System.Globalization.CultureInfo> class, the language attribute value needs to be one of the culture names predefined by <xref:System.Globalization.CultureInfo>. [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) is inheritable in the element tree (by XML rules, not necessarily because of dependency property inheritance) and its default value is an empty string if it is not assigned explicitly.
|
||||
XAML uses [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) to represent the language attribute of an element. To take advantage of the <xref:System.Globalization.CultureInfo> class, the language attribute value needs to be one of the culture names predefined by <xref:System.Globalization.CultureInfo>. [xml:lang](/dotnet/desktop/xaml-services/xml-language-handling) is inheritable in the element tree (by XML rules, not necessarily because of dependency property inheritance) and its default value is an empty string if it is not assigned explicitly.
|
||||
|
||||
The language attribute is very useful for specifying dialects. For example, French has different spelling, vocabulary, and pronunciation in France, Quebec, Belgium, and Switzerland. Also Chinese, Japanese, and Korean share code points in Unicode, but the ideographic shapes are different and they use totally different fonts.
|
||||
|
||||
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example uses the `fr-CA` language attribute to specify Canadian French.
|
||||
The following Extensible Application Markup Language (XAML) example uses the `fr-CA` language attribute to specify Canadian French.
|
||||
|
||||
```xaml
|
||||
<TextBlock xml:lang="fr-CA">Découvrir la France</TextBlock>
|
||||
@@ -51,15 +51,15 @@ The following example shows a hexadecimal character reference. Notice that it ha
|
||||
|
||||
<a name="unicode"></a>
|
||||
### Unicode
|
||||
[!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] supports all Unicode features including surrogates. As long as the character set can be mapped to Unicode, it is supported. For example, GB18030 introduces some characters that are mapped to the Chinese, Japanese, and Korean (CFK) extension A and B and surrogate pairs, therefore it is fully supported. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application can use <xref:System.Globalization.StringInfo> to manipulate strings without understanding whether they have surrogate pairs or combining characters.
|
||||
WPF application can use <xref:System.Globalization.StringInfo> to manipulate strings without understanding whether they have surrogate pairs or combining characters.
|
||||
|
||||
<a name="design_intl_ui_with_xaml"></a>
|
||||
## Designing an International User Interface with XAML
|
||||
This section describes [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] features that you should consider when writing an application.
|
||||
This section describes user interface (UI) features that you should consider when writing an application.
|
||||
|
||||
<a name="intl_text"></a>
|
||||
### International Text
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] includes built-in processing for all Microsoft .NET Framework supported writing systems.
|
||||
WPF includes built-in processing for all Microsoft .NET Framework supported writing systems.
|
||||
|
||||
The following scripts are currently supported:
|
||||
|
||||
@@ -121,11 +121,11 @@ The following example shows a hexadecimal character reference. Notice that it ha
|
||||
|
||||
OpenType fonts allow the handling of large glyph sets using Unicode encoding. Such encoding enables broad international support as well as for typographic glyph variants.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] text rendering is powered by Microsoft ClearType sub-pixel technology that supports resolution independence. This significantly improves legibility and provides the ability to support high quality magazine style documents for all scripts.
|
||||
WPF text rendering is powered by Microsoft ClearType sub-pixel technology that supports resolution independence. This significantly improves legibility and provides the ability to support high quality magazine style documents for all scripts.
|
||||
|
||||
<a name="intl_layout"></a>
|
||||
### International Layout
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a very convenient way to support horizontal, bidirectional, and vertical layouts. In presentation framework the <xref:System.Windows.FrameworkElement.FlowDirection%2A> property can be used to define layout. The flow direction patterns are:
|
||||
WPF provides a very convenient way to support horizontal, bidirectional, and vertical layouts. In presentation framework the <xref:System.Windows.FrameworkElement.FlowDirection%2A> property can be used to define layout. The flow direction patterns are:
|
||||
|
||||
- *LeftToRight* - horizontal layout for Latin, East Asian and so forth.
|
||||
|
||||
@@ -137,20 +137,20 @@ The following example shows a hexadecimal character reference. Notice that it ha
|
||||
|
||||
<a name="mui"></a>
|
||||
### Multilingual User Interface
|
||||
Multilingual User Interfaces (MUI) is a Microsoft support for switching UIs from one language to another. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application uses the assembly model to support MUI. One application contains language-neutral assemblies as well as language-dependent satellite resource assemblies. The entry point is a managed .EXE in the main assembly. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] resource loader takes advantage of the Framework's resource manager to support resource lookup and fallback. Multiple language satellite assemblies work with the same main assembly. The resource assembly that is loaded depends on the <xref:System.Globalization.CultureInfo.CurrentUICulture%2A> of the current thread.
|
||||
Multilingual User Interfaces (MUI) is a Microsoft support for switching UIs from one language to another. A WPF application uses the assembly model to support MUI. One application contains language-neutral assemblies as well as language-dependent satellite resource assemblies. The entry point is a managed .EXE in the main assembly. WPF resource loader takes advantage of the Framework's resource manager to support resource lookup and fallback. Multiple language satellite assemblies work with the same main assembly. The resource assembly that is loaded depends on the <xref:System.Globalization.CultureInfo.CurrentUICulture%2A> of the current thread.
|
||||
|
||||
<a name="localizable_ui"></a>
|
||||
### Localizable User Interface
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications use [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to define their [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] allows developers to specify a hierarchy of objects with a set of properties and logic. The primary use of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is to develop [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications but it can be used to specify a hierarchy of any common language runtime (CLR) objects. Most developers use [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] to specify their application's [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] and use a programming language such as C# to react to user interaction.
|
||||
UI. UI and use a programming language such as C# to react to user interaction.
|
||||
|
||||
From a resource point of view, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file designed to describe a language-dependent [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] is a resource element and therefore its final distribution format must be localizable to support international languages. Because [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] cannot handle events many [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] applications contain blocks of code to do this. For more information, see [XAML in WPF](xaml-in-wpf.md). Code is stripped out and compiled into different binaries when a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is tokenized into the BAML form of XAML. The BAML form of XAML files, images, and other types of managed resource objects are embedded in the satellite resource assembly, which can be localized into other languages, or the main assembly when localization is not required.
|
||||
From a resource point of view, a UI is a resource element and therefore its final distribution format must be localizable to support international languages. Because XAML cannot handle events many XAML applications contain blocks of code to do this. For more information, see [XAML in WPF](xaml-in-wpf.md). Code is stripped out and compiled into different binaries when a XAML file is tokenized into the BAML form of XAML. The BAML form of XAML files, images, and other types of managed resource objects are embedded in the satellite resource assembly, which can be localized into other languages, or the main assembly when localization is not required.
|
||||
|
||||
> [!NOTE]
|
||||
> [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications support all the FrameworkCLR resources including string tables, images, and so forth.
|
||||
> WPF applications support all the FrameworkCLR resources including string tables, images, and so forth.
|
||||
|
||||
<a name="building_localizable_apps"></a>
|
||||
### Building Localizable Applications
|
||||
Localization means to adapt a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] to different cultures. To make a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application localizable, developers need to build all the localizable resources into a resource assembly. The resource assembly is localized into different languages, and the code-behind uses resource management API to load. One of the files required for a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application is a project file (.proj). All resources that you use in your application should be included in the project file. The following example from a .csproj file shows how to do this.
|
||||
Localization means to adapt a UI to different cultures. To make a WPF application localizable, developers need to build all the localizable resources into a resource assembly. The resource assembly is localized into different languages, and the code-behind uses resource management API to load. One of the files required for a WPF application is a project file (.proj). All resources that you use in your application should be included in the project file. The following example from a .csproj file shows how to do this.
|
||||
|
||||
```xml
|
||||
<Resource Include="data\picture1.jpg"/>
|
||||
|
||||
@@ -12,7 +12,7 @@ helpviewer_keywords:
|
||||
ms.assetid: d5d9274c-23b3-4859-8869-6e64403c9ca7
|
||||
---
|
||||
# Glyphs
|
||||
Glyphs are a low-level depiction of a character to be drawn on-screen. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides direct access to glyphs for customers who want to intercept and persist text after formatting.
|
||||
Glyphs are a low-level depiction of a character to be drawn on-screen. Windows Presentation Foundation (WPF) provides direct access to glyphs for customers who want to intercept and persist text after formatting.
|
||||
|
||||
## In This Section
|
||||
[Introduction to the GlyphRun Object and Glyphs Element](introduction-to-the-glyphrun-object-and-glyphs-element.md)
|
||||
|
||||
@@ -11,7 +11,7 @@ ms.assetid: 08dd1606-02a2-4122-9351-c0afd2ec3a70
|
||||
---
|
||||
# Graphics Rendering Tiers
|
||||
|
||||
A rendering tier defines a level of graphics hardware capability and performance for a device that runs a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application.
|
||||
A rendering tier defines a level of graphics hardware capability and performance for a device that runs a WPF application.
|
||||
|
||||
<a name="graphics_hardware"></a>
|
||||
|
||||
@@ -31,7 +31,7 @@ A rendering tier defines a level of graphics hardware capability and performance
|
||||
|
||||
## Rendering Tier Definitions
|
||||
|
||||
The features of the graphics hardware determine the rendering capability of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] system defines three rendering tiers:
|
||||
The features of the graphics hardware determine the rendering capability of a WPF application. The WPF system defines three rendering tiers:
|
||||
|
||||
- **Rendering Tier 0** No graphics hardware acceleration. All graphics features use software acceleration. The DirectX version level is less than version 9.0.
|
||||
|
||||
@@ -50,7 +50,7 @@ A rendering tier defines a level of graphics hardware capability and performance
|
||||
> [!NOTE]
|
||||
> Starting in the .NET Framework 4, rendering tier 1 has been redefined to only include graphics hardware that supports DirectX 9.0 or greater. Graphics hardware that supports DirectX 7 or 8 is now defined as rendering tier 0.
|
||||
|
||||
A rendering tier value of 1 or 2 means that most of the graphics features of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] will use hardware acceleration if the necessary system resources are available and have not been exhausted. This corresponds to a DirectX version that is greater than or equal to 9.0.
|
||||
A rendering tier value of 1 or 2 means that most of the graphics features of WPF will use hardware acceleration if the necessary system resources are available and have not been exhausted. This corresponds to a DirectX version that is greater than or equal to 9.0.
|
||||
|
||||
The following table shows the differences in graphics hardware requirements for rendering tier 1 and rendering tier 2:
|
||||
|
||||
@@ -68,10 +68,10 @@ A rendering tier defines a level of graphics hardware capability and performance
|
||||
|-------------|-----------|
|
||||
|2D rendering|Most 2D rendering is supported.|
|
||||
|3D rasterization|Most 3D rasterization is supported.|
|
||||
|3D anisotropic filtering|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] attempts to use anisotropic filtering when rendering 3D content. Anisotropic filtering refers to enhancing the image quality of textures on surfaces that are far away and steeply angled with respect to the camera.|
|
||||
|3D MIP mapping|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] attempts to use MIP mapping when rendering 3D content. MIP mapping improves the quality of texture rendering when a texture occupies a smaller field of view in a <xref:System.Windows.Controls.Viewport3D>.|
|
||||
|3D anisotropic filtering|WPF attempts to use anisotropic filtering when rendering 3D content. Anisotropic filtering refers to enhancing the image quality of textures on surfaces that are far away and steeply angled with respect to the camera.|
|
||||
|3D MIP mapping|WPF attempts to use MIP mapping when rendering 3D content. MIP mapping improves the quality of texture rendering when a texture occupies a smaller field of view in a <xref:System.Windows.Controls.Viewport3D>.|
|
||||
|Radial gradients|While supported, avoid the use of <xref:System.Windows.Media.RadialGradientBrush> on large objects.|
|
||||
|3D lighting calculations|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] performs per-vertex lighting, which means that a light intensity must be calculated at each vertex for each material applied to a mesh.|
|
||||
|3D lighting calculations|WPF performs per-vertex lighting, which means that a light intensity must be calculated at each vertex for each material applied to a mesh.|
|
||||
|Text rendering|Subpixel font rendering uses available pixel shaders on the graphics hardware.|
|
||||
|
||||
The following features and capabilities are hardware accelerated only for rendering tier 2:
|
||||
@@ -84,40 +84,40 @@ A rendering tier defines a level of graphics hardware capability and performance
|
||||
|
||||
|Feature|Notes|
|
||||
|-------------|-----------|
|
||||
|Printed content|All printed content is rendered using the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] software pipeline.|
|
||||
|Printed content|All printed content is rendered using the WPF software pipeline.|
|
||||
|Rasterized content that uses <xref:System.Windows.Media.Imaging.RenderTargetBitmap>|Any content rendered by using the <xref:System.Windows.Media.Imaging.RenderTargetBitmap.Render%2A> method of <xref:System.Windows.Media.Imaging.RenderTargetBitmap>.|
|
||||
|Tiled content that uses <xref:System.Windows.Media.TileBrush>|Any tiled content in which the <xref:System.Windows.Media.TileBrush.TileMode%2A> property of the <xref:System.Windows.Media.TileBrush> is set to <xref:System.Windows.Media.TileMode.Tile>.|
|
||||
|Surfaces that exceed the maximum texture size of the graphics hardware|For most graphics hardware, large surfaces are 2048x2048 or 4096x4096 pixels in size.|
|
||||
|Any operation whose video RAM requirement exceeds the memory of the graphics hardware|You can monitor application video RAM usage by using the Perforator tool that is included in the [WPF Performance Suite](/previous-versions/dotnet/netframework-4.0/aa969767(v=vs.100)) in the Windows SDK.|
|
||||
|Layered windows|Layered windows allow [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications to render content to the screen in a non-rectangular window. On operating systems that support Windows Display Driver Model (WDDM), such as Windows Vista and Windows 7, layered windows are hardware accelerated. On other systems, such as Windows XP, layered windows are rendered by software with no hardware acceleration.<br /><br /> You can enable layered windows in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] by setting the following <xref:System.Windows.Window> properties:<br /><br /> - <xref:System.Windows.Window.WindowStyle%2A> = <xref:System.Windows.WindowStyle.None><br />- <xref:System.Windows.Window.AllowsTransparency%2A> = `true`<br />- <xref:System.Windows.Controls.Control.Background%2A> = <xref:System.Windows.Media.Brushes.Transparent%2A>|
|
||||
|Layered windows|Layered windows allow WPF applications to render content to the screen in a non-rectangular window. On operating systems that support Windows Display Driver Model (WDDM), such as Windows Vista and Windows 7, layered windows are hardware accelerated. On other systems, such as Windows XP, layered windows are rendered by software with no hardware acceleration.<br /><br /> You can enable layered windows in WPF by setting the following <xref:System.Windows.Window> properties:<br /><br /> - <xref:System.Windows.Window.WindowStyle%2A> = <xref:System.Windows.WindowStyle.None><br />- <xref:System.Windows.Window.AllowsTransparency%2A> = `true`<br />- <xref:System.Windows.Controls.Control.Background%2A> = <xref:System.Windows.Media.Brushes.Transparent%2A>|
|
||||
|
||||
<a name="other_resources"></a>
|
||||
|
||||
## Other Resources
|
||||
|
||||
The following resources can help you analyze the performance characteristics of your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application.
|
||||
The following resources can help you analyze the performance characteristics of your WPF application.
|
||||
|
||||
### Graphics Rendering Registry Settings
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides four registry settings for controlling [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] rendering:
|
||||
WPF provides four registry settings for controlling WPF rendering:
|
||||
|
||||
|Setting|Description|
|
||||
|-------------|-----------------|
|
||||
|**Disable Hardware Acceleration Option**|Specifies whether hardware acceleration should be enabled.|
|
||||
|**Maximum Multisample Value**|Specifies the degree of multisampling for antialiasing 3D content.|
|
||||
|**Required Video Driver Date Setting**|Specifies whether the system disables hardware acceleration for drivers released before November 2004.|
|
||||
|**Use Reference Rasterizer Option**|Specifies whether [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] should use the reference rasterizer.|
|
||||
|**Use Reference Rasterizer Option**|Specifies whether WPF should use the reference rasterizer.|
|
||||
|
||||
These settings can be accessed by any external configuration utility that knows how to reference the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. For more information, see [Graphics Rendering Registry Settings](../graphics-multimedia/graphics-rendering-registry-settings.md).
|
||||
These settings can be accessed by any external configuration utility that knows how to reference the WPF registry settings. These settings can also be created or modified by accessing the values directly by using the Windows Registry Editor. For more information, see [Graphics Rendering Registry Settings](../graphics-multimedia/graphics-rendering-registry-settings.md).
|
||||
|
||||
### WPF Performance Profiling Tools
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The following table lists the performance profiling tools that are included in the Windows SDK tool, WPF Performance Suite:
|
||||
WPF provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your application and determine the types of performance optimizations you can apply. The following table lists the performance profiling tools that are included in the Windows SDK tool, WPF Performance Suite:
|
||||
|
||||
|Tool|Description|
|
||||
|----------|-----------------|
|
||||
|Perforator|Use for analyzing rendering behavior.|
|
||||
|Visual Profiler|Use for profiling the use of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] services, such as layout and event handling, by elements in the visual tree.|
|
||||
|Visual Profiler|Use for profiling the use of WPF services, such as layout and event handling, by elements in the visual tree.|
|
||||
|
||||
The WPF Performance Suite provides a rich, graphical view of performance data. For more information about WPF performance tools, see [WPF Performance Suite](/previous-versions/dotnet/netframework-4.0/aa969767(v=vs.100)).
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ See [WPF and Win32 Interoperation](wpf-and-win32-interoperation.md).
|
||||
|
||||
## A Walkthrough of Win32 Inside Windows Presentation Framework (HwndHost)
|
||||
|
||||
To reuse Win32 content inside [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, use <xref:System.Windows.Interop.HwndHost>, which is a control that makes HWNDs look like [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] content. Like <xref:System.Windows.Interop.HwndSource>, <xref:System.Windows.Interop.HwndHost> is straightforward to use: derive from <xref:System.Windows.Interop.HwndHost> and implement `BuildWindowCore` and `DestroyWindowCore` methods, then instantiate your <xref:System.Windows.Interop.HwndHost> derived class and place it inside your [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application.
|
||||
To reuse Win32 content inside WPF applications, use <xref:System.Windows.Interop.HwndHost>, which is a control that makes HWNDs look like WPF content. Like <xref:System.Windows.Interop.HwndSource>, <xref:System.Windows.Interop.HwndHost> is straightforward to use: derive from <xref:System.Windows.Interop.HwndHost> and implement `BuildWindowCore` and `DestroyWindowCore` methods, then instantiate your <xref:System.Windows.Interop.HwndHost> derived class and place it inside your WPF application.
|
||||
|
||||
If your Win32 logic is already packaged as a control, then your `BuildWindowCore` implementation is little more than a call to `CreateWindow`. For example, to create a Win32 LISTBOX control in C++:
|
||||
|
||||
@@ -41,11 +41,11 @@ virtual void DestroyWindowCore(HandleRef hwnd) override {
|
||||
}
|
||||
```
|
||||
|
||||
But suppose the Win32 code is not quite so self-contained? If so, you can create a Win32 dialog box and embed its contents into a larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. The sample shows this in Visual Studio and C++, although it is also possible to do this in a different language or at the command line.
|
||||
But suppose the Win32 code is not quite so self-contained? If so, you can create a Win32 dialog box and embed its contents into a larger WPF application. The sample shows this in Visual Studio and C++, although it is also possible to do this in a different language or at the command line.
|
||||
|
||||
Start with a simple dialog, which is compiled into a C++ DLL project.
|
||||
|
||||
Next, introduce the dialog into the larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application:
|
||||
Next, introduce the dialog into the larger WPF application:
|
||||
|
||||
- Compile the DLL as managed (`/clr`)
|
||||
|
||||
@@ -59,7 +59,7 @@ Next, introduce the dialog into the larger [!INCLUDE[TLA2#tla_winclient](../../.
|
||||
|
||||
- Override `OnMnemonic` method to support mnemonics
|
||||
|
||||
- Instantiate the <xref:System.Windows.Interop.HwndHost> subclass and put it under the right [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] element
|
||||
- Instantiate the <xref:System.Windows.Interop.HwndHost> subclass and put it under the right WPF element
|
||||
|
||||
### Turn the Dialog into a Control
|
||||
|
||||
@@ -227,7 +227,7 @@ Both MSGs have the same data, but sometimes it is easier to work with the unmana
|
||||
}
|
||||
```
|
||||
|
||||
Back to `TranslateAccelerator`. The basic principle is to call the Win32 function `IsDialogMessage` to do as much work as possible, but `IsDialogMessage` does not have access to anything outside the dialog. As a user tab around the dialog, when tabbing runs past the last control in our dialog, you need to set focus to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] portion by calling `IKeyboardInputSite::OnNoMoreStops`.
|
||||
Back to `TranslateAccelerator`. The basic principle is to call the Win32 function `IsDialogMessage` to do as much work as possible, but `IsDialogMessage` does not have access to anything outside the dialog. As a user tab around the dialog, when tabbing runs past the last control in our dialog, you need to set focus to the WPF portion by calling `IKeyboardInputSite::OnNoMoreStops`.
|
||||
|
||||
```cpp
|
||||
// Win32's IsDialogMessage() will handle most of the tabbing, but doesn't know
|
||||
@@ -249,7 +249,7 @@ if (m.message == WM_KEYDOWN && m.wParam == VK_TAB) {
|
||||
}
|
||||
```
|
||||
|
||||
Finally, call `IsDialogMessage`. But one of the responsibilities of a `TranslateAccelerator` method is telling [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] whether you handled the keystroke or not. If you did not handle it, the input event can tunnel and bubble through the rest of the application. Here, you will expose a quirk of keyboard messange handling and the nature of the input architecture in Win32. Unfortunately, `IsDialogMessage` does not return in any way whether it handles a particular keystroke. Even worse, it will call `DispatchMessage()` on keystrokes it should not handle! So you will have to reverse-engineer `IsDialogMessage`, and only call it for the keys you know it will handle:
|
||||
Finally, call `IsDialogMessage`. But one of the responsibilities of a `TranslateAccelerator` method is telling WPF whether you handled the keystroke or not. If you did not handle it, the input event can tunnel and bubble through the rest of the application. Here, you will expose a quirk of keyboard messange handling and the nature of the input architecture in Win32. Unfortunately, `IsDialogMessage` does not return in any way whether it handles a particular keystroke. Even worse, it will call `DispatchMessage()` on keystrokes it should not handle! So you will have to reverse-engineer `IsDialogMessage`, and only call it for the keys you know it will handle:
|
||||
|
||||
```cpp
|
||||
// Only call IsDialogMessage for keys it will do something with.
|
||||
@@ -274,7 +274,7 @@ if (msg.message == WM_SYSKEYDOWN || msg.message == WM_KEYDOWN) {
|
||||
|
||||
### Override TabInto Method to Support Tabbing
|
||||
|
||||
Now that you have implemented `TranslateAccelerator`, a user can tab around inside the dialog box and tab out of it into the greater [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. But a user cannot tab back into the dialog box. To solve that, you override `TabInto`:
|
||||
Now that you have implemented `TranslateAccelerator`, a user can tab around inside the dialog box and tab out of it into the greater WPF application. But a user cannot tab back into the dialog box. To solve that, you override `TabInto`:
|
||||
|
||||
```cpp
|
||||
public:
|
||||
@@ -325,11 +325,11 @@ virtual bool OnMnemonic(System::Windows::Interop::MSG% msg, ModifierKeys modifie
|
||||
};
|
||||
```
|
||||
|
||||
Why not call `IsDialogMessage` here? You have the same issue as before--you need to be able to inform [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] code whether your code handled the keystroke or not, and `IsDialogMessage` cannot do that. There is also a second issue, because `IsDialogMessage` refuses to process the mnemonic if the focused HWND is not inside the dialog box.
|
||||
Why not call `IsDialogMessage` here? You have the same issue as before--you need to be able to inform WPF code whether your code handled the keystroke or not, and `IsDialogMessage` cannot do that. There is also a second issue, because `IsDialogMessage` refuses to process the mnemonic if the focused HWND is not inside the dialog box.
|
||||
|
||||
### Instantiate the HwndHost Derived Class
|
||||
|
||||
Finally, now that all the key and tab support is in place, you can put your <xref:System.Windows.Interop.HwndHost> into the larger [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. If the main application is written in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], the easiest way to put it in the right place is to leave an empty <xref:System.Windows.Controls.Border> element where you want to put the <xref:System.Windows.Interop.HwndHost>. Here you create a <xref:System.Windows.Controls.Border> named `insertHwndHostHere`:
|
||||
Finally, now that all the key and tab support is in place, you can put your <xref:System.Windows.Interop.HwndHost> into the larger WPF application. If the main application is written in XAML, the easiest way to put it in the right place is to leave an empty <xref:System.Windows.Controls.Border> element where you want to put the <xref:System.Windows.Interop.HwndHost>. Here you create a <xref:System.Windows.Controls.Border> named `insertHwndHostHere`:
|
||||
|
||||
```xaml
|
||||
<Window x:Class="WPFApplication1.Window1"
|
||||
|
||||
+3
-3
@@ -13,10 +13,10 @@ ms.assetid: 269c61e0-6bd9-4291-9bed-1c5ee66da486
|
||||
# How to: Add an Event Handler Using Code
|
||||
This example shows how to add an event handler to an element by using code.
|
||||
|
||||
If you want to add an event handler to a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] element, and the markup page that contains the element has already been loaded, you must add the handler using code. Alternatively, if you are building up the element tree for an application entirely using code and not declaring any elements using [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can call specific methods to add event handlers to the constructed element tree.
|
||||
If you want to add an event handler to a XAML element, and the markup page that contains the element has already been loaded, you must add the handler using code. Alternatively, if you are building up the element tree for an application entirely using code and not declaring any elements using XAML, you can call specific methods to add event handlers to the constructed element tree.
|
||||
|
||||
## Example
|
||||
The following example adds a new <xref:System.Windows.Controls.Button> to an existing page that is initially defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. A code-behind file implements an event handler method and then adds that method as a new event handler on the <xref:System.Windows.Controls.Button>.
|
||||
The following example adds a new <xref:System.Windows.Controls.Button> to an existing page that is initially defined in XAML. A code-behind file implements an event handler method and then adds that method as a new event handler on the <xref:System.Windows.Controls.Button>.
|
||||
|
||||
The C# example uses the `+=` operator to assign a handler to an event. This is the same operator that is used to assign a handler in the common language runtime (CLR) event handling model. Microsoft Visual Basic does not support this operator as a means of adding event handlers. It instead requires one of two techniques:
|
||||
|
||||
@@ -30,7 +30,7 @@ This example shows how to add an event handler to an element by using code.
|
||||
[!code-vb[RoutedEventAddRemoveHandler#Handler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/RoutedEventAddRemoveHandler/VisualBasic/default.xaml.vb#handler)]
|
||||
|
||||
> [!NOTE]
|
||||
> Adding an event handler in the initially parsed [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page is much simpler. Within the object element where you want to add the event handler, add an attribute that matches the name of the event that you want to handle. Then specify the value of that attribute as the name of the event handler method that you defined in the code-behind file of the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page. For more information, see [XAML in WPF](xaml-in-wpf.md) or [Routed Events Overview](routed-events-overview.md).
|
||||
> Adding an event handler in the initially parsed XAML page is much simpler. Within the object element where you want to add the event handler, add an attribute that matches the name of the event that you want to handle. Then specify the value of that attribute as the name of the event handler method that you defined in the code-behind file of the XAML page. For more information, see [XAML in WPF](xaml-in-wpf.md) or [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
+2
-2
@@ -10,11 +10,11 @@ helpviewer_keywords:
|
||||
ms.assetid: edcce050-0576-4edb-a31a-3f909637b452
|
||||
---
|
||||
# How to: Add an Owner Type for a Dependency Property
|
||||
This example shows how to add a class as an owner of a dependency property registered for a different type. By doing this, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader and property system are both able to recognize the class as an additional owner of the property. Adding as owner optionally allows the adding class to provide type-specific metadata.
|
||||
This example shows how to add a class as an owner of a dependency property registered for a different type. By doing this, the WPF XAML reader and property system are both able to recognize the class as an additional owner of the property. Adding as owner optionally allows the adding class to provide type-specific metadata.
|
||||
|
||||
In the following example, `StateProperty` is a property registered by the `MyStateControl` class. The class `UnrelatedStateControl` adds itself as an owner of the `StateProperty` using the <xref:System.Windows.DependencyProperty.AddOwner%2A> method, specifically using the signature that allows for new metadata for the dependency property as it exists on the adding type. Notice that you should provide common language runtime (CLR) accessors for the property similar to the example shown in the [Implement a Dependency Property](how-to-implement-a-dependency-property.md) example, as well as re-expose the dependency property identifier on the class being added as owner.
|
||||
|
||||
Without wrappers, the dependency property would still work from the perspective of programmatic access using <xref:System.Windows.DependencyObject.GetValue%2A> or <xref:System.Windows.DependencyObject.SetValue%2A>. But you typically want to parallel this property-system behavior with the CLR property wrappers. The wrappers make it easier to set the dependency property programmatically, and make it possible to set the properties as [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attributes.
|
||||
Without wrappers, the dependency property would still work from the perspective of programmatic access using <xref:System.Windows.DependencyObject.GetValue%2A> or <xref:System.Windows.DependencyObject.SetValue%2A>. But you typically want to parallel this property-system behavior with the CLR property wrappers. The wrappers make it easier to set the dependency property programmatically, and make it possible to set the properties as XAML attributes.
|
||||
|
||||
To find out how to override default metadata, see [Override Metadata for a Dependency Property](how-to-override-metadata-for-a-dependency-property.md).
|
||||
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@ ms.assetid: 363de99e-8ecc-438c-ac4a-f9147432ebd6
|
||||
This example shows you how to create a focus visual style in resources and apply the style to a control, using the <xref:System.Windows.FrameworkElement.FocusVisualStyle%2A> property.
|
||||
|
||||
## Example
|
||||
The following example defines a style that creates additional control compositing that only applies when that control is keyboard focused in the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. This is accomplished by defining a style with a <xref:System.Windows.Controls.ControlTemplate>, then referencing that style as a resource when setting the <xref:System.Windows.FrameworkElement.FocusVisualStyle%2A> property.
|
||||
The following example defines a style that creates additional control compositing that only applies when that control is keyboard focused in the user interface (UI). This is accomplished by defining a style with a <xref:System.Windows.Controls.ControlTemplate>, then referencing that style as a resource when setting the <xref:System.Windows.FrameworkElement.FocusVisualStyle%2A> property.
|
||||
|
||||
An external rectangle resembling a border is placed outside of the rectangular area. Unless otherwise modified, the sizing of the style uses the <xref:System.Windows.FrameworkElement.ActualHeight%2A> and <xref:System.Windows.FrameworkElement.ActualWidth%2A> of the rectangular control where the focus visual style is applied. This example sets negative values for the <xref:System.Windows.FrameworkElement.Margin%2A> to make the border appear slightly outside the focused control.
|
||||
|
||||
|
||||
+1
-1
@@ -11,7 +11,7 @@ helpviewer_keywords:
|
||||
ms.assetid: e3ca88f3-6e94-4b61-82fc-42104c10b761
|
||||
---
|
||||
# How to: Build a Table Programmatically
|
||||
The following examples show how to programmatically create a <xref:System.Windows.Documents.Table> and populate it with content. The contents of the table are apportioned into five rows (represented by <xref:System.Windows.Documents.TableRow> objects contained in a <xref:System.Windows.Documents.Table.RowGroups%2A> object) and six columns (represented by <xref:System.Windows.Documents.TableColumn> objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] element.
|
||||
The following examples show how to programmatically create a <xref:System.Windows.Documents.Table> and populate it with content. The contents of the table are apportioned into five rows (represented by <xref:System.Windows.Documents.TableRow> objects contained in a <xref:System.Windows.Documents.Table.RowGroups%2A> object) and six columns (represented by <xref:System.Windows.Documents.TableColumn> objects). The rows are used for different presentation purposes, including a title row intended to title the entire table, a header row to describe the columns of data in the table, and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be comprised of text, images, or nearly any other user interface (UI) element.
|
||||
|
||||
## Create a table
|
||||
First, a <xref:System.Windows.Documents.FlowDocument> is created to host the <xref:System.Windows.Documents.Table>, and a new <xref:System.Windows.Documents.Table> is created and added to the contents of the <xref:System.Windows.Documents.FlowDocument>.
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@ ms.assetid: 7e246802-3625-47a7-ae9d-c8a2a40fd040
|
||||
# How to: Change the Color of an Element Using Focus Events
|
||||
This example shows how to change the color of an element when it gains and loses focus by using the <xref:System.Windows.UIElement.GotFocus> and <xref:System.Windows.UIElement.LostFocus> events.
|
||||
|
||||
This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file.
|
||||
This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file.
|
||||
|
||||
## Example
|
||||
The following XAML creates the user interface, which consists of two <xref:System.Windows.Controls.Button> objects, and attaches event handlers for the <xref:System.Windows.UIElement.GotFocus> and <xref:System.Windows.UIElement.LostFocus> events to the <xref:System.Windows.Controls.Button> objects.
|
||||
|
||||
@@ -13,7 +13,7 @@ ms.assetid: 08c945a7-8ab0-4320-acf3-0b4955a344c2
|
||||
# How to: Change the Cursor Type
|
||||
This example shows how to change the <xref:System.Windows.Input.Cursor> of the mouse pointer for a specific element and for the application.
|
||||
|
||||
This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code behind file.
|
||||
This example consists of a Extensible Application Markup Language (XAML) file and a code behind file.
|
||||
|
||||
## Example
|
||||
The user interface is created, which consists of a <xref:System.Windows.Controls.ComboBox> to select the desired <xref:System.Windows.Input.Cursor>, a pair of <xref:System.Windows.Controls.RadioButton> objects to determine if the cursor change applies to only a single element or applies to the entire application, and a <xref:System.Windows.Controls.Border> which is the element that the new cursor is applied to.
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@ ms.assetid: 30d25554-4c82-4df9-a8d6-35683a4a13bb
|
||||
## Example
|
||||
The following code example shows how to change the value of the <xref:System.Windows.Controls.TextBlock.TextWrapping%2A> property programmatically.
|
||||
|
||||
Three <xref:System.Windows.Controls.Button> elements are placed within a <xref:System.Windows.Controls.StackPanel> element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. Each <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event for a <xref:System.Windows.Controls.Button> corresponds with an event handler in the code. The event handlers use the same name as the <xref:System.Windows.Controls.TextBlock.TextWrapping%2A> value they will apply to `txt2` when the button is clicked. Also, the text in `txt1` (a <xref:System.Windows.Controls.TextBlock> not shown in the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]) is updated to reflect the change in the property.
|
||||
Three <xref:System.Windows.Controls.Button> elements are placed within a <xref:System.Windows.Controls.StackPanel> element in XAML. Each <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event for a <xref:System.Windows.Controls.Button> corresponds with an event handler in the code. The event handlers use the same name as the <xref:System.Windows.Controls.TextBlock.TextWrapping%2A> value they will apply to `txt2` when the button is clicked. Also, the text in `txt1` (a <xref:System.Windows.Controls.TextBlock> not shown in the XAML) is updated to reflect the change in the property.
|
||||
|
||||
[!code-xaml[TextWrapProperty#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextWrapProperty/VisualBasic/Pane1.xaml#1)]
|
||||
|
||||
|
||||
@@ -17,14 +17,14 @@ For your custom event to support event routing, you need to register a <xref:Sys
|
||||
|
||||
Note that even though the event is raised through the `OnTap` virtual method in this particular example, how you raise your event or how your event responds to changes depends on your needs.
|
||||
|
||||
Note also that this example basically implements an entire subclass of <xref:System.Windows.Controls.Button>; that subclass is built as a separate assembly and then instantiated as a custom class on a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page. This is to illustrate the concept that subclassed controls can be inserted into trees composed of other controls, and that in this situation, custom events on these controls have the very same event routing capabilities as any native [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] element does.
|
||||
Note also that this example basically implements an entire subclass of <xref:System.Windows.Controls.Button>; that subclass is built as a separate assembly and then instantiated as a custom class on a separate Windows Presentation Foundation (WPF) element does.
|
||||
|
||||
[!code-csharp[RoutedEventCustom#CustomClass](~/samples/snippets/csharp/VS_Snippets_Wpf/RoutedEventCustom/CSharp/SDKSampleLibrary/class1.cs#customclass)]
|
||||
[!code-vb[RoutedEventCustom#CustomClass](~/samples/snippets/visualbasic/VS_Snippets_Wpf/RoutedEventCustom/VB/SDKSampleLibrary/Class1.vb#customclass)]
|
||||
|
||||
[!code-xaml[RoutedEventCustom#Page](~/samples/snippets/csharp/VS_Snippets_Wpf/RoutedEventCustom/CSharp/RoutedEventCustomApp/default.xaml#page)]
|
||||
|
||||
Tunneling events are created the same way, but with <xref:System.Windows.RoutedEvent.RoutingStrategy%2A> set to <xref:System.Windows.RoutingStrategy.Tunnel> in the registration call. By convention, tunneling events in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] are prefixed with the word "Preview".
|
||||
Tunneling events are created the same way, but with <xref:System.Windows.RoutedEvent.RoutingStrategy%2A> set to <xref:System.Windows.RoutingStrategy.Tunnel> in the registration call. By convention, tunneling events in WPF are prefixed with the word "Preview".
|
||||
|
||||
To see an example of how bubbling events work, see [Handle a Routed Event](how-to-handle-a-routed-event.md).
|
||||
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@ ms.assetid: 3b20d028-6f1c-4b25-95d2-fa68cefbdb4c
|
||||
# How to: Create a Rollover Effect Using Events
|
||||
This example shows how to change the color of an element as the mouse pointer enters and leaves the area occupied by the element.
|
||||
|
||||
This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file.
|
||||
This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file.
|
||||
|
||||
> [!NOTE]
|
||||
> This example demonstrates how to use events, but the recommended way to achieve this same effect is to use a <xref:System.Windows.Trigger> in a style. For more information, see [Styling and Templating](../controls/styles-templates-overview.md).
|
||||
|
||||
@@ -14,7 +14,7 @@ ms.assetid: 4aa3cf6e-1953-4f26-8230-7c1409e5f28d
|
||||
---
|
||||
# How to: Create outlined text
|
||||
|
||||
In most cases, when you're adding ornamentation to text strings in your [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application, you are using text in terms of a collection of discrete characters, or glyphs. For example, you could create a linear gradient brush and apply it to the <xref:System.Windows.Controls.Control.Foreground%2A> property of a <xref:System.Windows.Controls.TextBox> object. When you display or edit the text box, the linear gradient brush is automatically applied to the current set of characters in the text string.
|
||||
In most cases, when you're adding ornamentation to text strings in your Windows Presentation Foundation (WPF) application, you are using text in terms of a collection of discrete characters, or glyphs. For example, you could create a linear gradient brush and apply it to the <xref:System.Windows.Controls.Control.Foreground%2A> property of a <xref:System.Windows.Controls.TextBox> object. When you display or edit the text box, the linear gradient brush is automatically applied to the current set of characters in the text string.
|
||||
|
||||

|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ ms.assetid: 6ab9c754-6001-4708-b479-5367f2fd1a35
|
||||
The examples in this section show how to create a shadow effect for displayed text.
|
||||
|
||||
## Example
|
||||
The <xref:System.Windows.Media.Effects.DropShadowEffect> object allows you to create a variety of drop shadow effects for [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] objects. The following example shows a drop shadow effect applied to text. In this case, the shadow is a soft shadow, which means the shadow color blurs.
|
||||
The <xref:System.Windows.Media.Effects.DropShadowEffect> object allows you to create a variety of drop shadow effects for Windows Presentation Foundation (WPF) objects. The following example shows a drop shadow effect applied to text. In this case, the shadow is a soft shadow, which means the shadow color blurs.
|
||||
|
||||

|
||||
|
||||
@@ -20,7 +20,7 @@ The examples in this section show how to create a shadow effect for displayed te
|
||||
[!code-xaml[TextShadowSnippets#TextShadowSnippet1](~/samples/snippets/csharp/VS_Snippets_Wpf/TextShadowSnippets/CS/SingleShadows.xaml#textshadowsnippet1)]
|
||||
|
||||
> [!NOTE]
|
||||
> These shadow effects do not go through the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] text rendering pipeline. As a result, ClearType is disabled when using these effects.
|
||||
> These shadow effects do not go through the Windows Presentation Foundation (WPF) text rendering pipeline. As a result, ClearType is disabled when using these effects.
|
||||
|
||||
The following example shows a hard drop shadow effect applied to text. In this case, the shadow is not blurred.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 83f2dc58-437e-4cdc-b5dd-0019810c7a85
|
||||
---
|
||||
# How to: Define a Table with XAML
|
||||
The following example demonstrates how to define a <xref:System.Windows.Documents.Table> using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. The example table has four columns (represented by <xref:System.Windows.Documents.TableColumn> elements) and several rows (represented by <xref:System.Windows.Documents.TableRow> elements) containing data as well as title, header, and footer information. Rows must be contained in a <xref:System.Windows.Documents.TableRowGroup> element. Each row in the table is comprised of one or more cells (represented by <xref:System.Windows.Documents.TableCell> elements). Content in a table cell must be contained in a <xref:System.Windows.Documents.Block> element; in this case <xref:System.Windows.Documents.Paragraph> elements are used. The table also hosts a hyperlink (represented by the <xref:System.Windows.Documents.Hyperlink> element) in the footer row.
|
||||
The following example demonstrates how to define a <xref:System.Windows.Documents.Table> using Extensible Application Markup Language (XAML). The example table has four columns (represented by <xref:System.Windows.Documents.TableColumn> elements) and several rows (represented by <xref:System.Windows.Documents.TableRow> elements) containing data as well as title, header, and footer information. Rows must be contained in a <xref:System.Windows.Documents.TableRowGroup> element. Each row in the table is comprised of one or more cells (represented by <xref:System.Windows.Documents.TableCell> elements). Content in a table cell must be contained in a <xref:System.Windows.Documents.Block> element; in this case <xref:System.Windows.Documents.Paragraph> elements are used. The table also hosts a hyperlink (represented by the <xref:System.Windows.Documents.Hyperlink> element) in the footer row.
|
||||
|
||||
## Example
|
||||
[!code-xaml[TableSnippetsXAML#_TableXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/TableSnippetsXAML/CS/Window1.xaml#_tablexaml)]
|
||||
|
||||
+2
-2
@@ -11,11 +11,11 @@ ms.assetid: b86b876b-0a10-489b-9a5d-581ea9b32406
|
||||
|
||||
# How to: Define and Reference a Resource
|
||||
|
||||
This example shows how to define a resource and reference it by using an attribute in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)].
|
||||
This example shows how to define a resource and reference it by using an attribute in Extensible Application Markup Language (XAML).
|
||||
|
||||
## Example
|
||||
|
||||
The following example defines two types of resources: a <xref:System.Windows.Media.SolidColorBrush> resource, and several <xref:System.Windows.Style> resources. The <xref:System.Windows.Media.SolidColorBrush> resource `MyBrush` is used to provide the value of several properties that each take a <xref:System.Windows.Media.Brush> type value. The <xref:System.Windows.Style> resources `PageBackground`, `TitleText` and `Label` each target a particular control type. The styles set a variety of different properties on the targeted controls, when that style resource is referenced by resource key and is used to set the <xref:System.Windows.FrameworkElement.Style%2A> property of several specific control elements defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
|
||||
The following example defines two types of resources: a <xref:System.Windows.Media.SolidColorBrush> resource, and several <xref:System.Windows.Style> resources. The <xref:System.Windows.Media.SolidColorBrush> resource `MyBrush` is used to provide the value of several properties that each take a <xref:System.Windows.Media.Brush> type value. The <xref:System.Windows.Style> resources `PageBackground`, `TitleText` and `Label` each target a particular control type. The styles set a variety of different properties on the targeted controls, when that style resource is referenced by resource key and is used to set the <xref:System.Windows.FrameworkElement.Style%2A> property of several specific control elements defined in XAML.
|
||||
|
||||
Note that one of the properties within the setters of the `Label` style also references the `MyBrush` resource defined earlier. This is a common technique, but it is important to remember that resources are parsed and entered into a resource dictionary in the order that they are given. Resources are also requested by the order found within the dictionary if you use the [StaticResource Markup Extension](staticresource-markup-extension.md) to reference them from within another resource. Make sure that any resource that you reference is defined earlier within the resources collection than where that resource is then requested. If necessary, you can work around the strict creation order of resource references by using a [DynamicResource Markup Extension](dynamicresource-markup-extension.md) to reference the resource at runtime instead, but you should be aware that this DynamicResource technique has performance consequences. For details, see [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define).
|
||||
|
||||
|
||||
+2
-2
@@ -13,10 +13,10 @@ ms.assetid: a66f39d2-ef4a-43a5-b454-a4ea0fe88655
|
||||
# How to: Detect When the Enter Key Pressed
|
||||
This example shows how to detect when the <xref:System.Windows.Input.Key.Enter> key is pressed on the keyboard.
|
||||
|
||||
This example consists of a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file and a code-behind file.
|
||||
This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file.
|
||||
|
||||
## Example
|
||||
When the user presses the <xref:System.Windows.Input.Key.Enter> key in the <xref:System.Windows.Controls.TextBox>, the input in the text box appears in another area of the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)].
|
||||
When the user presses the <xref:System.Windows.Input.Key.Enter> key in the <xref:System.Windows.Controls.TextBox>, the input in the text box appears in another area of the user interface (UI).
|
||||
|
||||
The following XAML creates the user interface, which consists of a <xref:System.Windows.Controls.StackPanel>, a <xref:System.Windows.Controls.TextBlock>, and a <xref:System.Windows.Controls.TextBox>.
|
||||
|
||||
|
||||
@@ -10,10 +10,10 @@ helpviewer_keywords:
|
||||
ms.assetid: d8016266-58d9-48f7-8298-a86b7ed49fbd
|
||||
---
|
||||
# How to: Enable a Command
|
||||
The following example demonstrates how to use commanding in [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]. The example shows how to associate a <xref:System.Windows.Input.RoutedCommand> to a <xref:System.Windows.Controls.Button>, create a <xref:System.Windows.Input.CommandBinding>, and create the event handlers which implement the <xref:System.Windows.Input.RoutedCommand>. For more information on commanding, see the [Commanding Overview](commanding-overview.md).
|
||||
The following example demonstrates how to use commanding in Windows Presentation Foundation (WPF). The example shows how to associate a <xref:System.Windows.Input.RoutedCommand> to a <xref:System.Windows.Controls.Button>, create a <xref:System.Windows.Input.CommandBinding>, and create the event handlers which implement the <xref:System.Windows.Input.RoutedCommand>. For more information on commanding, see the [Commanding Overview](commanding-overview.md).
|
||||
|
||||
## Example
|
||||
The first section of code creates the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)], which consists of a <xref:System.Windows.Controls.Button> and a <xref:System.Windows.Controls.StackPanel>, and creates a <xref:System.Windows.Input.CommandBinding> that associates the command handlers with the <xref:System.Windows.Input.RoutedCommand>.
|
||||
The first section of code creates the user interface (UI), which consists of a <xref:System.Windows.Controls.Button> and a <xref:System.Windows.Controls.StackPanel>, and creates a <xref:System.Windows.Input.CommandBinding> that associates the command handlers with the <xref:System.Windows.Input.RoutedCommand>.
|
||||
|
||||
The <xref:System.Windows.Input.ICommandSource.Command%2A> property of the <xref:System.Windows.Controls.Button> is associated with the <xref:System.Windows.Input.ApplicationCommands.Close%2A> command.
|
||||
|
||||
|
||||
+2
-2
@@ -11,7 +11,7 @@ ms.assetid: 95de9b9c-d804-405c-b2d1-49a88c1e0fe1
|
||||
---
|
||||
# How to: Enable Visual Styles in a Hybrid Application
|
||||
|
||||
This topic shows how to enable visual styles on a Windows Forms control hosted in a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]-based application.
|
||||
This topic shows how to enable visual styles on a Windows Forms control hosted in a WPF-based application.
|
||||
|
||||
If your application calls the <xref:System.Windows.Forms.Application.EnableVisualStyles%2A> method, most of your Windows Forms controls will automatically use visual styles. For more information, see [Rendering Controls with Visual Styles](/dotnet/framework/winforms/controls/rendering-controls-with-visual-styles).
|
||||
|
||||
@@ -21,7 +21,7 @@ This topic shows how to enable visual styles on a Windows Forms control hosted i
|
||||
|
||||
#### To enable Windows Forms visual styles
|
||||
|
||||
1. Create a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Application project named `HostingWfWithVisualStyles`.
|
||||
1. Create a WPF Application project named `HostingWfWithVisualStyles`.
|
||||
|
||||
2. In Solution Explorer, add references to the following assemblies.
|
||||
|
||||
|
||||
@@ -18,4 +18,4 @@ ms.assetid: 36e37791-55b9-4f01-a496-5cc10335e6a6
|
||||
[!code-csharp[TextOverview#100](~/samples/snippets/csharp/VS_Snippets_Wpf/TextOverview/CSharp/Window1.xaml.cs#100)]
|
||||
[!code-vb[TextOverview#100](~/samples/snippets/visualbasic/VS_Snippets_Wpf/TextOverview/visualbasic/window1.xaml.vb#100)]
|
||||
|
||||
If multiple versions of the same font family reside in the same directory, the [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] font enumeration returns the most recent version of the font. If the version information does not provide resolution, the font with latest timestamp is returned. If the timestamp information is equivalent, the font file that is first in alphabetical order is returned.
|
||||
If multiple versions of the same font family reside in the same directory, the Windows Presentation Foundation (WPF) font enumeration returns the most recent version of the font. If the version information does not provide resolution, the font with latest timestamp is returned. If the timestamp information is equivalent, the font file that is first in alphabetical order is returned.
|
||||
|
||||
@@ -12,7 +12,7 @@ ms.assetid: cfa7cf35-8aa2-4060-9454-872ed4af3f0e
|
||||
This example describes how to use the <xref:System.Windows.FrameworkElement.FindName%2A> method to find an element by its <xref:System.Windows.FrameworkElement.Name%2A> value.
|
||||
|
||||
## Example
|
||||
In this example, the method to find a particular element by its name is written as the event handler of a button. `stackPanel` is the <xref:System.Windows.FrameworkElement.Name%2A> of the root <xref:System.Windows.FrameworkElement> being searched, and the example method then visually indicates the found element by casting it as <xref:System.Windows.Controls.TextBlock> and changing one of the <xref:System.Windows.Controls.TextBlock> visible [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] properties.
|
||||
In this example, the method to find a particular element by its name is written as the event handler of a button. `stackPanel` is the <xref:System.Windows.FrameworkElement.Name%2A> of the root <xref:System.Windows.FrameworkElement> being searched, and the example method then visually indicates the found element by casting it as <xref:System.Windows.Controls.TextBlock> and changing one of the <xref:System.Windows.Controls.TextBlock> visible UI properties.
|
||||
|
||||
[!code-csharp[FEFindName#Find](~/samples/snippets/csharp/VS_Snippets_Wpf/FEFindName/CSharp/default.xaml.cs#find)]
|
||||
[!code-vb[FEFindName#Find](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FEFindName/VisualBasic/default.xaml.vb#find)]
|
||||
|
||||
@@ -14,7 +14,7 @@ ms.assetid: 0cf8d003-8441-4df4-807a-6db09347e829
|
||||
This example shows how to handle the <xref:System.Windows.FrameworkElement.Loaded?displayProperty=nameWithType> event, and an appropriate scenario for handling that event. The handler creates a <xref:System.Windows.Controls.Button> when the page loads.
|
||||
|
||||
## Example
|
||||
The following example uses [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] together with a code-behind file.
|
||||
The following example uses Extensible Application Markup Language (XAML) together with a code-behind file.
|
||||
|
||||
[!code-xaml[FELoaded#XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/FELoaded/CSharp/default.xaml#xaml)]
|
||||
|
||||
|
||||
@@ -13,11 +13,11 @@ ms.assetid: 157787b4-f469-4047-8777-5b034145f32e
|
||||
This example shows how bubbling events work and how to write a handler that can process the routed event data.
|
||||
|
||||
## Example
|
||||
In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], elements are arranged in an element tree structure. The parent element can participate in the handling of events that are initially raised by child elements in the element tree. This is possible because of event routing.
|
||||
In Windows Presentation Foundation (WPF), elements are arranged in an element tree structure. The parent element can participate in the handling of events that are initially raised by child elements in the element tree. This is possible because of event routing.
|
||||
|
||||
Routed events typically follow one of two routing strategies, bubbling or tunneling. This example focuses on the bubbling event and uses the <xref:System.Windows.Controls.Primitives.ButtonBase.Click?displayProperty=nameWithType> event to show how routing works.
|
||||
|
||||
The following example creates two <xref:System.Windows.Controls.Button> controls and uses [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] attribute syntax to attach an event handler to a common parent element, which in this example is <xref:System.Windows.Controls.StackPanel>. Instead of attaching individual event handlers for each <xref:System.Windows.Controls.Button> child element, the example uses attribute syntax to attach the event handler to the <xref:System.Windows.Controls.StackPanel> parent element. This event-handling pattern shows how to use event routing as a technique for reducing the number of elements where a handler is attached. All the bubbling events for each <xref:System.Windows.Controls.Button> route through the parent element.
|
||||
The following example creates two <xref:System.Windows.Controls.Button> controls and uses XAML attribute syntax to attach an event handler to a common parent element, which in this example is <xref:System.Windows.Controls.StackPanel>. Instead of attaching individual event handlers for each <xref:System.Windows.Controls.Button> child element, the example uses attribute syntax to attach the event handler to the <xref:System.Windows.Controls.StackPanel> parent element. This event-handling pattern shows how to use event routing as a technique for reducing the number of elements where a handler is attached. All the bubbling events for each <xref:System.Windows.Controls.Button> route through the parent element.
|
||||
|
||||
Note that on the parent <xref:System.Windows.Controls.StackPanel> element, the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event name specified as the attribute is partially qualified by naming the <xref:System.Windows.Controls.Button> class. The <xref:System.Windows.Controls.Button> class is a <xref:System.Windows.Controls.Primitives.ButtonBase> derived class that has the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event in its members listing. This partial qualification technique for attaching an event handler is necessary if the event that is being handled does not exist in the members listing of the element where the routed event handler is attached.
|
||||
|
||||
|
||||
+2
-2
@@ -15,11 +15,11 @@ ms.assetid: 8d8592ae-0c91-469e-a1cd-d179c4544548
|
||||
The following example shows how to hook up a <xref:System.Windows.Input.RoutedCommand> to a <xref:System.Windows.Controls.Control> which has built in support for the command. For a complete sample which hooks up commands to multiple sources, see the [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand) sample.
|
||||
|
||||
## Example
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, and <xref:System.Windows.Documents.EditingCommands>.
|
||||
Windows Presentation Foundation (WPF) provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, and <xref:System.Windows.Documents.EditingCommands>.
|
||||
|
||||
The static <xref:System.Windows.Input.RoutedCommand> objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a <xref:System.Windows.Input.CommandBinding>. Some controls have built in CommandBindings for some commands. This mechanism allows the semantics of a command to stay the same, while the actual implementation is can change. A <xref:System.Windows.Controls.TextBox>, for example, handles the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command differently than a control designed to support images, but the basic idea of what it means to paste something stays the same. The command logic cannot be supplied by the command, but rather must be supplied by the control or the application.
|
||||
|
||||
Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] do have built in support for some of the commands in the command library. <xref:System.Windows.Controls.TextBox>, for example, supports many of the application edit commands such as <xref:System.Windows.Input.ApplicationCommands.Paste%2A>, <xref:System.Windows.Input.ApplicationCommands.Copy%2A>, <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.ApplicationCommands.Redo%2A>, and <xref:System.Windows.Input.ApplicationCommands.Undo%2A>. The application developer does not have to do anything special to get these commands to work with these controls. If the <xref:System.Windows.Controls.TextBox> is the command target when the command is executed, it will handle the command using the <xref:System.Windows.Input.CommandBinding> that is built into the control.
|
||||
Many controls in WPF do have built in support for some of the commands in the command library. <xref:System.Windows.Controls.TextBox>, for example, supports many of the application edit commands such as <xref:System.Windows.Input.ApplicationCommands.Paste%2A>, <xref:System.Windows.Input.ApplicationCommands.Copy%2A>, <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.ApplicationCommands.Redo%2A>, and <xref:System.Windows.Input.ApplicationCommands.Undo%2A>. The application developer does not have to do anything special to get these commands to work with these controls. If the <xref:System.Windows.Controls.TextBox> is the command target when the command is executed, it will handle the command using the <xref:System.Windows.Input.CommandBinding> that is built into the control.
|
||||
|
||||
The following shows how to use a <xref:System.Windows.Controls.MenuItem> as the command source for the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command, where a <xref:System.Windows.Controls.TextBox> is the target of the command. All the logic that defines how the <xref:System.Windows.Controls.TextBox> performs the paste is built into the <xref:System.Windows.Controls.TextBox> control.
|
||||
|
||||
|
||||
+2
-2
@@ -15,9 +15,9 @@ ms.assetid: dad08f64-700b-46fb-ad3f-fbfee95f0dfe
|
||||
The following example shows how to hook up a <xref:System.Windows.Input.RoutedCommand> to a <xref:System.Windows.Controls.Control> which does not have built in support for the command. For a complete sample which hooks up commands to multiple sources, see the [Create a Custom RoutedCommand Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Input%20and%20Commands/CustomRoutedCommand) sample.
|
||||
|
||||
## Example
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, and <xref:System.Windows.Documents.EditingCommands>.
|
||||
Windows Presentation Foundation (WPF) provides a library of common commands which application programmers encounter regularly. The classes which comprise the command library are: <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, <xref:System.Windows.Input.MediaCommands>, and <xref:System.Windows.Documents.EditingCommands>.
|
||||
|
||||
The static <xref:System.Windows.Input.RoutedCommand> objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a <xref:System.Windows.Input.CommandBinding>. Many controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] have built in support for some of the commands in the command library. <xref:System.Windows.Controls.TextBox>, for example, supports many of the application edit commands such as <xref:System.Windows.Input.ApplicationCommands.Paste%2A>, <xref:System.Windows.Input.ApplicationCommands.Copy%2A>, <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.ApplicationCommands.Redo%2A>, and <xref:System.Windows.Input.ApplicationCommands.Undo%2A>. The application developer does not have to do anything special to get these commands to work with these controls. If the <xref:System.Windows.Controls.TextBox> is the command target when the command is executed, it will handle the command using the <xref:System.Windows.Input.CommandBinding> that is built into the control.
|
||||
The static <xref:System.Windows.Input.RoutedCommand> objects which make up these classes do not supply command logic. The logic for the command is associated with the command with a <xref:System.Windows.Input.CommandBinding>. Many controls in WPF have built in support for some of the commands in the command library. <xref:System.Windows.Controls.TextBox>, for example, supports many of the application edit commands such as <xref:System.Windows.Input.ApplicationCommands.Paste%2A>, <xref:System.Windows.Input.ApplicationCommands.Copy%2A>, <xref:System.Windows.Input.ApplicationCommands.Cut%2A>, <xref:System.Windows.Input.ApplicationCommands.Redo%2A>, and <xref:System.Windows.Input.ApplicationCommands.Undo%2A>. The application developer does not have to do anything special to get these commands to work with these controls. If the <xref:System.Windows.Controls.TextBox> is the command target when the command is executed, it will handle the command using the <xref:System.Windows.Input.CommandBinding> that is built into the control.
|
||||
|
||||
The following shows how to use a <xref:System.Windows.Controls.Button> as the command source for the <xref:System.Windows.Input.ApplicationCommands.Open%2A> command. A <xref:System.Windows.Input.CommandBinding> is created that associates the specified <xref:System.Windows.Input.CanExecuteRoutedEventHandler> and the <xref:System.Windows.Input.CanExecuteRoutedEventHandler> with the <xref:System.Windows.Input.RoutedCommand>.
|
||||
|
||||
|
||||
+1
-1
@@ -11,7 +11,7 @@ helpviewer_keywords:
|
||||
ms.assetid: 855fd6d7-19ac-493c-bf5e-2f40b57cdc92
|
||||
---
|
||||
# How to: Implement a Dependency Property
|
||||
This example shows how to back a common language runtime (CLR) property with a <xref:System.Windows.DependencyProperty> field, thus defining a dependency property. When you define your own properties and want them to support many aspects of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] functionality, including styles, data binding, inheritance, animation, and default values, you should implement them as a dependency property.
|
||||
This example shows how to back a common language runtime (CLR) property with a <xref:System.Windows.DependencyProperty> field, thus defining a dependency property. When you define your own properties and want them to support many aspects of Windows Presentation Foundation (WPF) functionality, including styles, data binding, inheritance, animation, and default values, you should implement them as a dependency property.
|
||||
|
||||
## Example
|
||||
The following example first registers a dependency property by calling the <xref:System.Windows.DependencyProperty.Register%2A> method. The name of the identifier field that you use to store the name and characteristics of the dependency property must be the <xref:System.Windows.DependencyProperty.Name%2A> you chose for the dependency property as part of the <xref:System.Windows.DependencyProperty.Register%2A> call, appended by the literal string `Property`. For instance, if you register a dependency property with a <xref:System.Windows.DependencyProperty.Name%2A> of `Location`, then the identifier field that you define for the dependency property must be named `LocationProperty`.
|
||||
|
||||
@@ -13,7 +13,7 @@ ms.assetid: e3a2c84c-74fe-45a4-8501-5813f9dbfed2
|
||||
To provide the ability to print from you application, you can simply create and open a <xref:System.Windows.Controls.PrintDialog> object.
|
||||
|
||||
## Example
|
||||
The <xref:System.Windows.Controls.PrintDialog> control provides a single entry point for [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], configuration, and XPS job submission. The control is easy to use and can be instantiated by using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] markup or code. The following example demonstrates how to instantiate and open the control in code and how to print from it. It also shows how to ensure that the dialog will give the user the option of setting a specific range of pages. The example code assumes that there is a file FixedDocumentSequence.xps in the root of the C: drive.
|
||||
The <xref:System.Windows.Controls.PrintDialog> control provides a single entry point for UI, configuration, and XPS job submission. The control is easy to use and can be instantiated by using Extensible Application Markup Language (XAML) markup or code. The following example demonstrates how to instantiate and open the control in code and how to print from it. It also shows how to ensure that the dialog will give the user the option of setting a specific range of pages. The example code assumes that there is a file FixedDocumentSequence.xps in the root of the C: drive.
|
||||
|
||||
[!code-csharp[printdialog#1](~/samples/snippets/csharp/VS_Snippets_Wpf/PrintDialog/CSharp/Window1.xaml.cs#1)]
|
||||
[!code-vb[printdialog#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/PrintDialog/visualbasic/window1.xaml.vb#1)]
|
||||
|
||||
+2
-2
@@ -13,10 +13,10 @@ ms.assetid: 50b20415-14bc-405c-baf3-2fb254fffde3
|
||||
# How to: Make an Object Follow the Mouse Pointer
|
||||
This example shows how to change the dimensions of an object when the mouse pointer moves on the screen.
|
||||
|
||||
The example includes an [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file that creates the [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] and a code-behind file that creates the event handler.
|
||||
The example includes an user interface (UI) and a code-behind file that creates the event handler.
|
||||
|
||||
## Example
|
||||
The following XAML creates the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], which consists of an <xref:System.Windows.Shapes.Ellipse> inside of a <xref:System.Windows.Controls.StackPanel>, and attaches the event handler for the <xref:System.Windows.UIElement.MouseMove> event.
|
||||
The following XAML creates the UI, which consists of an <xref:System.Windows.Shapes.Ellipse> inside of a <xref:System.Windows.Controls.StackPanel>, and attaches the event handler for the <xref:System.Windows.UIElement.MouseMove> event.
|
||||
|
||||
[!code-xaml[mouseMoveWithPointer#MouseMoveWithPointerXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/mouseMoveWithPointer/CSharp/Window1.xaml#mousemovewithpointerxaml)]
|
||||
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@ ms.assetid: 6bb8bb54-f576-41db-a9a7-24102ddeb490
|
||||
---
|
||||
# How to: Open a File That is Dropped on a RichTextBox Control
|
||||
|
||||
In [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)], the <xref:System.Windows.Controls.TextBox>, <xref:System.Windows.Controls.RichTextBox>, and <xref:System.Windows.Documents.FlowDocument> controls all have built-in drag-and-drop functionality. The built-in functionality enables drag-and-drop of text within and between the controls. However, it does not enable opening a file by dropping the file on the control. These controls also mark the drag-and-drop events as handled. As a result, by default, you cannot add your own event handlers to provide functionality to open dropped files.
|
||||
In Windows Presentation Foundation (WPF), the <xref:System.Windows.Controls.TextBox>, <xref:System.Windows.Controls.RichTextBox>, and <xref:System.Windows.Documents.FlowDocument> controls all have built-in drag-and-drop functionality. The built-in functionality enables drag-and-drop of text within and between the controls. However, it does not enable opening a file by dropping the file on the control. These controls also mark the drag-and-drop events as handled. As a result, by default, you cannot add your own event handlers to provide functionality to open dropped files.
|
||||
|
||||
To add additional handling for drag-and-drop events in these controls, use the <xref:System.Windows.UIElement.AddHandler%28System.Windows.RoutedEvent%2CSystem.Delegate%2CSystem.Boolean%29> method to add your event handlers for the drag-and-drop events. Set the `handledEventsToo` parameter to `true` to have the specified handler be invoked for a routed event that has already been marked as handled by another element along the event route.
|
||||
|
||||
|
||||
+1
-1
@@ -14,7 +14,7 @@ ms.assetid: f90f026e-60d8-428a-933d-edf0dba4441f
|
||||
This example shows how to override default dependency property metadata that comes from an inherited class, by calling the <xref:System.Windows.DependencyProperty.OverrideMetadata%2A> method and providing type-specific metadata.
|
||||
|
||||
## Example
|
||||
By defining its <xref:System.Windows.PropertyMetadata>, a class can define the dependency property's behaviors, such as its default value and property system callbacks. Many dependency property classes already have default metadata established as part of their registration process. This includes the dependency properties that are part of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] API. A class that inherits the dependency property through its class inheritance can override the original metadata so that the characteristics of the property that can be altered through metadata will match any subclass-specific requirements.
|
||||
By defining its <xref:System.Windows.PropertyMetadata>, a class can define the dependency property's behaviors, such as its default value and property system callbacks. Many dependency property classes already have default metadata established as part of their registration process. This includes the dependency properties that are part of the WPF API. A class that inherits the dependency property through its class inheritance can override the original metadata so that the characteristics of the property that can be altered through metadata will match any subclass-specific requirements.
|
||||
|
||||
Overriding metadata on a dependency property must be done prior to that property being placed in use by the property system (this equates to the time that specific instances of objects that register the property are instantiated). Calls to <xref:System.Windows.DependencyProperty.OverrideMetadata%2A> must be performed within the static constructors of the type that provides itself as the `forType` parameter of <xref:System.Windows.DependencyProperty.OverrideMetadata%2A>. If you attempt to change metadata once instances of the owner type exist, this will not raise exceptions, but will result in inconsistent behaviors in the property system. Also, metadata can only be overridden once per type. Subsequent attempts to override metadata on the same type will raise an exception.
|
||||
|
||||
|
||||
+2
-2
@@ -11,7 +11,7 @@ ms.assetid: 0b1c0a3f-b19e-43d6-bcc9-eb3ec4e555ad
|
||||
---
|
||||
# How to: Programmatically Print XPS Files
|
||||
|
||||
You can use one overload of the <xref:System.Printing.PrintQueue.AddJob%2A> method to print XML Paper Specification (XPS) files without opening a <xref:System.Windows.Controls.PrintDialog> or, in principle, any [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] at all.
|
||||
You can use one overload of the <xref:System.Printing.PrintQueue.AddJob%2A> method to print XML Paper Specification (XPS) files without opening a <xref:System.Windows.Controls.PrintDialog> or, in principle, any user interface (UI) at all.
|
||||
|
||||
You can also print XPS files using the many <xref:System.Windows.Xps.XpsDocumentWriter.Write%2A?displayProperty=nameWithType> and <xref:System.Windows.Xps.XpsDocumentWriter.WriteAsync%2A?displayProperty=nameWithType> methods. For more information, see [Printing an XPS Document](/previous-versions/dotnet/netframework-3.5/ms771525(v=vs.90)).
|
||||
|
||||
@@ -29,7 +29,7 @@ The main steps to using the three-parameter <xref:System.Printing.PrintQueue.Add
|
||||
|
||||
4. Call the method, specifying a job name, the file to be printed, and a <xref:System.Boolean> flag indicating whether or not the printer is an XPSDrv printer.
|
||||
|
||||
The example below shows how to batch print all XPS files in a directory. Although the application prompts the user to specify the directory, the three-parameter <xref:System.Printing.PrintQueue.AddJob%28System.String%2CSystem.String%2CSystem.Boolean%29> method does not require a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. It can be used in any code path where you have an XPS file name and path that you can pass to it.
|
||||
The example below shows how to batch print all XPS files in a directory. Although the application prompts the user to specify the directory, the three-parameter <xref:System.Printing.PrintQueue.AddJob%28System.String%2CSystem.String%2CSystem.Boolean%29> method does not require a user interface (UI). It can be used in any code path where you have an XPS file name and path that you can pass to it.
|
||||
|
||||
The three-parameter <xref:System.Printing.PrintQueue.AddJob%28System.String%2CSystem.String%2CSystem.Boolean%29> overload of <xref:System.Printing.PrintQueue.AddJob%2A> must run in a single thread apartment whenever the <xref:System.Boolean> parameter is `false`, which it must be when a non-XPSDrv printer is being used. However, the default apartment state for .NET is multiple thread. This default must be reversed since the example assumes a non-XPSDrv printer.
|
||||
|
||||
|
||||
@@ -10,12 +10,12 @@ helpviewer_keywords:
|
||||
ms.assetid: eb47bd94-0451-4f8d-8fb6-95f7812ac05b
|
||||
---
|
||||
# How to: Register an Attached Property
|
||||
This example shows how to register an attached property and provide public accessors so that you can use the property in both [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] and code. Attached properties are a syntax concept defined by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)]. Most attached properties for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] types are also implemented as dependency properties. You can use dependency properties on any <xref:System.Windows.DependencyObject> types.
|
||||
This example shows how to register an attached property and provide public accessors so that you can use the property in both WPF types are also implemented as dependency properties. You can use dependency properties on any <xref:System.Windows.DependencyObject> types.
|
||||
|
||||
## Example
|
||||
The following example shows how to register an attached property as a dependency property, by using the <xref:System.Windows.DependencyProperty.RegisterAttached%2A> method. The provider class has the option of providing default metadata for the property that is applicable when the property is used on another class, unless that class overrides the metadata. In this example, the default value of the `IsBubbleSource` property is set to `false`.
|
||||
|
||||
The provider class for an attached property (even if it is not registered as a dependency property) must provide static get and set accessors that follow the naming convention `Set`*[AttachedPropertyName]* and `Get`*[AttachedPropertyName]*. These accessors are required so that the acting [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] reader can recognize the property as an attribute in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and resolve the appropriate types.
|
||||
The provider class for an attached property (even if it is not registered as a dependency property) must provide static get and set accessors that follow the naming convention `Set`*[AttachedPropertyName]* and `Get`*[AttachedPropertyName]*. These accessors are required so that the acting XAML reader can recognize the property as an attribute in XAML and resolve the appropriate types.
|
||||
|
||||
[!code-csharp[WPFAquariumSln#RegisterAttachedBubbler](~/samples/snippets/csharp/VS_Snippets_Wpf/WPFAquariumSln/CSharp/WPFAquariumObjects/Class1.cs#registerattachedbubbler)]
|
||||
[!code-vb[WPFAquariumSln#RegisterAttachedBubbler](~/samples/snippets/visualbasic/VS_Snippets_Wpf/WPFAquariumSln/visualbasic/wpfaquariumobjects/class1.vb#registerattachedbubbler)]
|
||||
|
||||
@@ -25,7 +25,7 @@ ms.assetid: fac36cc9-dd01-41ca-9bde-9d33e3790bbe
|
||||
[!code-csharp[AdornerForStrokes#1](~/samples/snippets/csharp/VS_Snippets_Wpf/AdornerForStrokes/CSharp/RotatingAdornerForStrokes.cs#1)]
|
||||
[!code-vb[AdornerForStrokes#1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/AdornerForStrokes/VisualBasic/RotatingAdornerForStrokes.vb#1)]
|
||||
|
||||
The following example is a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file that defines an <xref:System.Windows.Controls.InkPresenter> and populates it with ink. The `Window_Loaded` event handler adds the custom adorner to the <xref:System.Windows.Controls.InkPresenter>.
|
||||
The following example is a Extensible Application Markup Language (XAML) file that defines an <xref:System.Windows.Controls.InkPresenter> and populates it with ink. The `Window_Loaded` event handler adds the custom adorner to the <xref:System.Windows.Controls.InkPresenter>.
|
||||
|
||||
[!code-xaml[AdornerForStrokes#2](~/samples/snippets/csharp/VS_Snippets_Wpf/AdornerForStrokes/CSharp/Window1.xaml#2)]
|
||||
|
||||
|
||||
+1
-1
@@ -13,7 +13,7 @@ ms.assetid: 70ebee01-6f87-4352-8dd4-402c65eaaed6
|
||||
# How to: Set Margins of Elements and Controls
|
||||
This example describes how to set the <xref:System.Windows.FrameworkElement.Margin%2A> property, by changing any existing property value for the margin in code-behind. The <xref:System.Windows.FrameworkElement.Margin%2A> property is a property of the <xref:System.Windows.FrameworkElement> base element, and is thus inherited by a variety of controls and other elements.
|
||||
|
||||
This example is written in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], with a code-behind file that the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] refers to. The code-behind is shown in both a C# and a Microsoft Visual Basic version.
|
||||
This example is written in XAML refers to. The code-behind is shown in both a C# and a Microsoft Visual Basic version.
|
||||
|
||||
## Example
|
||||
[!code-xaml[FEMarginProgrammatic#XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/FEMarginProgrammatic/CSharp/default.xaml#xaml)]
|
||||
|
||||
+2
-2
@@ -9,9 +9,9 @@ ms.assetid: ab9de407-e0c1-4047-bdf0-24951bf73879
|
||||
# How to: Use a Grid for Automatic Layout
|
||||
This example describes how to use a grid in the automatic layout approach to creating a localizable application.
|
||||
|
||||
Localization of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] can be a time consuming process. Often localizers need to re-size and reposition elements in addition to translating text. In the past each language that a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] was adapted for required adjustment. Now with the capabilities of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily re-sized and repositioned is called `auto layout`.
|
||||
Localization of a UI was adapted for required adjustment. Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily re-sized and repositioned is called `auto layout`.
|
||||
|
||||
The following [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] example demonstrates using a grid to position some buttons and text. Notice that the height and width of the cells are set to `Auto`; therefore the cell that contains the button with an image adjusts to fit the image. Because the <xref:System.Windows.Controls.Grid> element can adjust to its content it can be useful when taking the automatic layout approach to designing applications that can be localized.
|
||||
The following Extensible Application Markup Language (XAML) example demonstrates using a grid to position some buttons and text. Notice that the height and width of the cells are set to `Auto`; therefore the cell that contains the button with an image adjusts to fit the image. Because the <xref:System.Windows.Controls.Grid> element can adjust to its content it can be useful when taking the automatic layout approach to designing applications that can be localized.
|
||||
|
||||
## Example
|
||||
The following example shows how to use a grid.
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ This example shows how to use a <xref:System.Windows.ResourceDictionary> to pack
|
||||
|
||||
[!code-xaml[StringLocalizationSample#ReferencingStringResourceDictionary](~/samples/snippets/csharp/VS_Snippets_Wpf/StringLocalizationSample/CSharp/App.xaml#referencingstringresourcedictionary)]
|
||||
|
||||
3. Use the string resource from markup, using [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] like the following.
|
||||
3. Use the string resource from markup, using Extensible Application Markup Language (XAML) like the following.
|
||||
|
||||
[!code-xaml[StringLocalizationSample#GetLocalizedResourceFromMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/StringLocalizationSample/CSharp/MainWindow.xaml#getlocalizedresourcefrommarkup)]
|
||||
|
||||
|
||||
+1
-1
@@ -15,7 +15,7 @@ ms.assetid: 52682194-d7fd-499c-8005-73fcc84e7b2c
|
||||
|
||||
This example shows how to create an instance of <xref:System.Windows.ThicknessConverter> and use it to change the thickness of a border.
|
||||
|
||||
The example defines a custom method called `changeThickness`; this method first converts the contents of a <xref:System.Windows.Controls.ListBoxItem>, as defined in a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file, to an instance of <xref:System.Windows.Thickness>, and later converts the content into a <xref:System.String>. This method passes the <xref:System.Windows.Controls.ListBoxItem> to a <xref:System.Windows.ThicknessConverter> object, which converts the <xref:System.Windows.Controls.ContentControl.Content%2A> of a <xref:System.Windows.Controls.ListBoxItem> to an instance of <xref:System.Windows.Thickness>. This value is then passed back as the value of the <xref:System.Windows.Controls.Border.BorderThickness%2A> property of the <xref:System.Windows.Controls.Border>.
|
||||
The example defines a custom method called `changeThickness`; this method first converts the contents of a <xref:System.Windows.Controls.ListBoxItem>, as defined in a separate Extensible Application Markup Language (XAML) file, to an instance of <xref:System.Windows.Thickness>, and later converts the content into a <xref:System.String>. This method passes the <xref:System.Windows.Controls.ListBoxItem> to a <xref:System.Windows.ThicknessConverter> object, which converts the <xref:System.Windows.Controls.ContentControl.Content%2A> of a <xref:System.Windows.Controls.ListBoxItem> to an instance of <xref:System.Windows.Thickness>. This value is then passed back as the value of the <xref:System.Windows.Controls.Border.BorderThickness%2A> property of the <xref:System.Windows.Controls.Border>.
|
||||
|
||||
This example does not run.
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ This example shows how to use application resources.
|
||||
[!code-xaml[ResourcesApplication#PreTemplateResource](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/app.xaml#pretemplateresource)]
|
||||
[!code-xaml[ResourcesApplication#PostTemplateResource](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/app.xaml#posttemplateresource)]
|
||||
|
||||
The following example shows a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page that references the application-level resource that the previous example defined. The resource is referenced by using a [StaticResource Markup Extension](staticresource-markup-extension.md) that specifies the unique resource key for the requested resource. No resource with key of "GelButton" is found in the current page, so the resource lookup scope for the requested resource continues beyond the current page and into the defined application-level resources.
|
||||
The following example shows a XAML page that references the application-level resource that the previous example defined. The resource is referenced by using a [StaticResource Markup Extension](staticresource-markup-extension.md) that specifies the unique resource key for the requested resource. No resource with key of "GelButton" is found in the current page, so the resource lookup scope for the requested resource continues beyond the current page and into the defined application-level resources.
|
||||
|
||||
[!code-xaml[ResourcesApplication#ConsumingPage](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourcesApplication/CS/page1.xaml#consumingpage)]
|
||||
|
||||
|
||||
+2
-2
@@ -9,11 +9,11 @@ ms.assetid: 96c206d0-9e77-4784-9d2d-5045aed2021c
|
||||
# How to: Use Automatic Layout to Create a Button
|
||||
This example describes how to use the automatic layout approach to create a button in a localizable application.
|
||||
|
||||
Localization of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] can be a time consuming process. Often localizers need to resize and reposition elements in addition to translating text. In the past each language that a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] was adapted for required adjustment. Now with the capabilities of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily resized and repositioned is called `automatic layout`.
|
||||
Localization of a UI was adapted for required adjustment. Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that reduce the need for adjustment. The approach to writing applications that can be more easily resized and repositioned is called `automatic layout`.
|
||||
|
||||
## Example
|
||||
|
||||
The following two [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] examples create applications that instantiate a button; one with English text and one with Spanish text. Notice that the code is the same except for the text; the button adjusts to fit the text.
|
||||
The following two Extensible Application Markup Language (XAML) examples create applications that instantiate a button; one with English text and one with Spanish text. Notice that the code is the same except for the text; the button adjusts to fit the text.
|
||||
|
||||
[!code-xaml[LocalizationBtn_snip#1](~/samples/snippets/csharp/VS_Snippets_Wpf/LocalizationBtn_snip/CS/Pane1.xaml#1)]
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ System resources expose a number of system metrics as resources to help develope
|
||||
> [!NOTE]
|
||||
> Dynamic resources have the keyword *Key* appended to the property name.
|
||||
|
||||
The following example shows how to access and use system font dynamic resources to style or customize a button. This [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example creates a button style that assigns <xref:System.Windows.SystemFonts> values to a button.
|
||||
The following example shows how to access and use system font dynamic resources to style or customize a button. This XAML example creates a button style that assigns <xref:System.Windows.SystemFonts> values to a button.
|
||||
|
||||
## Example
|
||||
[!code-xaml[SystemRes_snip#FontDynamicResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/MyApp.xaml#fontdynamicresources)]
|
||||
|
||||
@@ -12,7 +12,7 @@ System resources expose a number of system metrics as resources to help develope
|
||||
> [!NOTE]
|
||||
> Dynamic resources have the keyword *Key* appended to the property name.
|
||||
|
||||
The following example shows how to access and use system parameter dynamic resources to style or customize a button. This [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] example sizes a button by assigning <xref:System.Windows.SystemParameters> values to the button's width and height.
|
||||
The following example shows how to access and use system parameter dynamic resources to style or customize a button. This XAML example sizes a button by assigning <xref:System.Windows.SystemParameters> values to the button's width and height.
|
||||
|
||||
## Example
|
||||
[!code-xaml[SystemRes_snip#ParameterDynamicResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/MyApp.xaml#parameterdynamicresources)]
|
||||
|
||||
@@ -16,7 +16,7 @@ This example shows how to use the static resources of the <xref:System.Windows.S
|
||||
## Example
|
||||
System resources expose several system-determined values as both resources and properties in order to help you create visuals that are consistent with system settings. <xref:System.Windows.SystemFonts> is a class that contains both system font values as static properties, and properties that reference resource keys that can be used to access those values dynamically at run time. For example, <xref:System.Windows.SystemFonts.CaptionFontFamily%2A> is a <xref:System.Windows.SystemFonts> value, and <xref:System.Windows.SystemFonts.CaptionFontFamilyKey%2A> is a corresponding resource key.
|
||||
|
||||
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can use the members of <xref:System.Windows.SystemFonts> as either static properties or dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the font metric to automatically update while the application runs; otherwise, use a static value reference.
|
||||
In XAML, you can use the members of <xref:System.Windows.SystemFonts> as either static properties or dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the font metric to automatically update while the application runs; otherwise, use a static value reference.
|
||||
|
||||
> [!NOTE]
|
||||
> The resource keys have the suffix "Key" appended to the property name.
|
||||
@@ -25,7 +25,7 @@ This example shows how to use the static resources of the <xref:System.Windows.S
|
||||
|
||||
[!code-xaml[SystemRes_snip#FontStaticResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml#fontstaticresources)]
|
||||
|
||||
To use the values of <xref:System.Windows.SystemFonts> in code, you do not have to use either a static value or a dynamic resource reference. Instead, use the non-key properties of the <xref:System.Windows.SystemFonts> class. Although the non-key properties are apparently defined as static properties, the run-time behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] as hosted by the system will reevaluate the properties in real time and will properly account for user-driven changes to system values. The following example shows how to specify the font settings of a button.
|
||||
To use the values of <xref:System.Windows.SystemFonts> in code, you do not have to use either a static value or a dynamic resource reference. Instead, use the non-key properties of the <xref:System.Windows.SystemFonts> class. Although the non-key properties are apparently defined as static properties, the run-time behavior of WPF as hosted by the system will reevaluate the properties in real time and will properly account for user-driven changes to system values. The following example shows how to specify the font settings of a button.
|
||||
|
||||
[!code-csharp[SystemRes_snip#FontResourcesCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml.cs#fontresourcescode)]
|
||||
[!code-vb[SystemRes_snip#FontResourcesCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SystemRes_snip/VisualBasic/Pane1.xaml.vb#fontresourcescode)]
|
||||
|
||||
@@ -14,13 +14,13 @@ This example shows how to access and use the properties of <xref:System.Windows.
|
||||
## Example
|
||||
System resources expose several system based settings as resources in order to help you create visuals that are consistent with system settings. <xref:System.Windows.SystemParameters> is a class that contains both system parameter value properties, and resource keys that bind to the values. For example, <xref:System.Windows.SystemParameters.FullPrimaryScreenHeight%2A> is a <xref:System.Windows.SystemParameters> property value and <xref:System.Windows.SystemParameters.FullPrimaryScreenHeightKey%2A> is the corresponding resource key.
|
||||
|
||||
In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], you can use the members of <xref:System.Windows.SystemParameters> as either a static property usage, or a dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the system based value to update automatically while the application runs; otherwise, use a static reference. Resource keys have the suffix `Key` appended to the property name.
|
||||
In XAML, you can use the members of <xref:System.Windows.SystemParameters> as either a static property usage, or a dynamic resource references (with the static property value as the key). Use a dynamic resource reference if you want the system based value to update automatically while the application runs; otherwise, use a static reference. Resource keys have the suffix `Key` appended to the property name.
|
||||
|
||||
The following example shows how to access and use the static values of <xref:System.Windows.SystemParameters> to style or customize a button. This markup example sizes a button by applying <xref:System.Windows.SystemParameters> values to a button.
|
||||
|
||||
[!code-xaml[SystemRes_snip#ParameterStaticResources](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml#parameterstaticresources)]
|
||||
|
||||
To use the values of <xref:System.Windows.SystemParameters> in code, you do not have to use either static references or dynamic resource references. Instead, use the values of the <xref:System.Windows.SystemParameters> class. Although the non-key properties are apparently defined as static properties, the runtime behavior of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] as hosted by the system will reevaluate the properties in realtime, and will properly account for user-driven changes to system values. The following example shows how to set the width and height of a button by using <xref:System.Windows.SystemParameters> values.
|
||||
To use the values of <xref:System.Windows.SystemParameters> in code, you do not have to use either static references or dynamic resource references. Instead, use the values of the <xref:System.Windows.SystemParameters> class. Although the non-key properties are apparently defined as static properties, the runtime behavior of WPF as hosted by the system will reevaluate the properties in realtime, and will properly account for user-driven changes to system values. The following example shows how to set the width and height of a button by using <xref:System.Windows.SystemParameters> values.
|
||||
|
||||
[!code-csharp[SystemRes_snip#ParameterResourcesCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SystemRes_snip/CSharp/Pane1.xaml.cs#parameterresourcescode)]
|
||||
[!code-vb[SystemRes_snip#ParameterResourcesCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SystemRes_snip/VisualBasic/Pane1.xaml.vb#parameterresourcescode)]
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@ ms.assetid: 3b0592bd-7223-4860-a108-a5d72f3a9178
|
||||
## Example
|
||||
This example shows how to create an instance of <xref:System.Windows.FontSizeConverter> and use it to change a font size.
|
||||
|
||||
The example defines a custom method called `changeSize` that converts the contents of a <xref:System.Windows.Controls.ListBoxItem>, as defined in a separate [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] file, to an instance of <xref:System.Double>, and later into a <xref:System.String>. This method passes the <xref:System.Windows.Controls.ListBoxItem> to a <xref:System.Windows.FontSizeConverter> object, which converts the <xref:System.Windows.Controls.ContentControl.Content%2A> of a <xref:System.Windows.Controls.ListBoxItem> to an instance of <xref:System.Double>. This value is then passed back as the value of the <xref:System.Windows.Controls.TextBlock.FontSize%2A> property of the <xref:System.Windows.Controls.TextBlock> element.
|
||||
The example defines a custom method called `changeSize` that converts the contents of a <xref:System.Windows.Controls.ListBoxItem>, as defined in a separate Extensible Application Markup Language (XAML) file, to an instance of <xref:System.Double>, and later into a <xref:System.String>. This method passes the <xref:System.Windows.Controls.ListBoxItem> to a <xref:System.Windows.FontSizeConverter> object, which converts the <xref:System.Windows.Controls.ContentControl.Content%2A> of a <xref:System.Windows.Controls.ListBoxItem> to an instance of <xref:System.Double>. This value is then passed back as the value of the <xref:System.Windows.Controls.TextBlock.FontSize%2A> property of the <xref:System.Windows.Controls.TextBlock> element.
|
||||
|
||||
This example also defines a second custom method that is called `changeFamily`. This method converts the <xref:System.Windows.Controls.ContentControl.Content%2A> of the <xref:System.Windows.Controls.ListBoxItem> to a <xref:System.String>, and then passes that value to the <xref:System.Windows.Controls.TextBlock.FontFamily%2A> property of the <xref:System.Windows.Controls.TextBlock> element.
|
||||
|
||||
|
||||
+4
-4
@@ -12,22 +12,22 @@ helpviewer_keywords:
|
||||
ms.assetid: 7b8dfc9b-46ac-4ce8-b7bb-035734d688b7
|
||||
---
|
||||
# Initialization for Object Elements Not in an Object Tree
|
||||
Some aspects of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] initialization are deferred to processes that typically rely on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be necessary in order to initialize an element that is not connected to either tree.
|
||||
Some aspects of Windows Presentation Foundation (WPF) initialization are deferred to processes that typically rely on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be necessary in order to initialize an element that is not connected to either tree.
|
||||
|
||||
## Elements and the Logical Tree
|
||||
When you create an instance of a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] class in code, you should be aware that several aspects of object initialization for a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] class are deliberately not a part of the code that is executed when calling the class constructor. Particularly for a control class, most of the visual representation of that control is not defined by the constructor. Instead, the visual representation is defined by the control's template. The template potentially comes from a variety of sources, but most often the template is obtained from theme styles. Templates are effectively late-binding; the necessary template is not attached to the control in question until the control is ready for layout. And the control is not ready for layout until it is attached to a logical tree that connects to a rendering surface at the root. It is that root-level element that initiates the rendering of all of its child elements as defined in the logical tree.
|
||||
When you create an instance of a Windows Presentation Foundation (WPF) class in code, you should be aware that several aspects of object initialization for a Windows Presentation Foundation (WPF) class are deliberately not a part of the code that is executed when calling the class constructor. Particularly for a control class, most of the visual representation of that control is not defined by the constructor. Instead, the visual representation is defined by the control's template. The template potentially comes from a variety of sources, but most often the template is obtained from theme styles. Templates are effectively late-binding; the necessary template is not attached to the control in question until the control is ready for layout. And the control is not ready for layout until it is attached to a logical tree that connects to a rendering surface at the root. It is that root-level element that initiates the rendering of all of its child elements as defined in the logical tree.
|
||||
|
||||
The visual tree also participates in this process. Elements that are part of the visual tree through the templates are also not fully instantiated until connected.
|
||||
|
||||
The consequences of this behavior are that certain operations that rely on the completed visual characteristics of an element require additional steps. An example is if you are attempting to get the visual characteristics of a class that was constructed but not yet attached to a tree. For instance, if you want to call <xref:System.Windows.Media.Imaging.RenderTargetBitmap.Render%2A> on a <xref:System.Windows.Media.Imaging.RenderTargetBitmap> and the visual you are passing is an element not connected to a tree, that element is not visually complete until additional initialization steps are completed.
|
||||
|
||||
### Using BeginInit and EndInit to Initialize the Element
|
||||
Various classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implement the <xref:System.ComponentModel.ISupportInitialize> interface. You use the <xref:System.ComponentModel.ISupportInitialize.BeginInit%2A> and <xref:System.ComponentModel.ISupportInitialize.EndInit%2A> methods of the interface to denote a region in your code that contains initialization steps (such as setting property values that affect rendering). After <xref:System.ComponentModel.ISupportInitialize.EndInit%2A> is called in the sequence, the layout system can process the element and start looking for an implicit style.
|
||||
Various classes in WPF implement the <xref:System.ComponentModel.ISupportInitialize> interface. You use the <xref:System.ComponentModel.ISupportInitialize.BeginInit%2A> and <xref:System.ComponentModel.ISupportInitialize.EndInit%2A> methods of the interface to denote a region in your code that contains initialization steps (such as setting property values that affect rendering). After <xref:System.ComponentModel.ISupportInitialize.EndInit%2A> is called in the sequence, the layout system can process the element and start looking for an implicit style.
|
||||
|
||||
If the element you are setting properties on is a <xref:System.Windows.FrameworkElement> or <xref:System.Windows.FrameworkContentElement> derived class, then you can call the class versions of <xref:System.Windows.FrameworkElement.BeginInit%2A> and <xref:System.Windows.FrameworkElement.EndInit%2A> rather than casting to <xref:System.ComponentModel.ISupportInitialize>.
|
||||
|
||||
### Sample Code
|
||||
The following example is sample code for a console application that uses rendering APIs and <xref:System.Windows.Markup.XamlReader.Load%28System.IO.Stream%29?displayProperty=nameWithType> of a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file to illustrate the proper placement of <xref:System.Windows.FrameworkElement.BeginInit%2A> and <xref:System.Windows.FrameworkElement.EndInit%2A> around other API calls that adjust properties that affect rendering.
|
||||
The following example is sample code for a console application that uses rendering APIs and <xref:System.Windows.Markup.XamlReader.Load%28System.IO.Stream%29?displayProperty=nameWithType> of a loose XAML file to illustrate the proper placement of <xref:System.Windows.FrameworkElement.BeginInit%2A> and <xref:System.Windows.FrameworkElement.EndInit%2A> around other API calls that adjust properties that affect rendering.
|
||||
|
||||
The example illustrates the main function only. The functions `Rasterize` and `Save` (not shown) are utility functions that take care of image processing and IO.
|
||||
|
||||
|
||||
@@ -9,10 +9,10 @@ helpviewer_keywords:
|
||||
ms.assetid: 69a1a3f9-acb5-4e2c-9c43-2e376c055ac4
|
||||
---
|
||||
# Inline Styles and Templates
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides <xref:System.Windows.Style> objects and template objects (<xref:System.Windows.FrameworkTemplate> subclasses) as a way to define the visual appearance of an element in resources, so that they can be used multiple times. For this reason, attributes in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] that take the types <xref:System.Windows.Style> and <xref:System.Windows.FrameworkTemplate> almost always make resource references to existing styles and templates rather than define new ones inline.
|
||||
XAML that take the types <xref:System.Windows.Style> and <xref:System.Windows.FrameworkTemplate> almost always make resource references to existing styles and templates rather than define new ones inline.
|
||||
|
||||
## Limitations of Inline Styles and Templates
|
||||
In [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)], style and template properties can technically be set in one of two ways. You can use attribute syntax to reference a style that was defined within a resource, for example `<`*object*`Style="{StaticResource`*myResourceKey*`}" .../>`. Or you can use property element syntax to define a style inline, for instance:
|
||||
In Extensible Application Markup Language (XAML), style and template properties can technically be set in one of two ways. You can use attribute syntax to reference a style that was defined within a resource, for example `<`*object*`Style="{StaticResource`*myResourceKey*`}" .../>`. Or you can use property element syntax to define a style inline, for instance:
|
||||
|
||||
`<` *object* `>`
|
||||
|
||||
@@ -24,7 +24,7 @@ ms.assetid: 69a1a3f9-acb5-4e2c-9c43-2e376c055ac4
|
||||
|
||||
`</` *object* `>`
|
||||
|
||||
The attribute usage is much more common. A style that is defined inline and not defined in resources is necessarily scoped to the containing element only, and cannot be re-used as easily because it has no resource key. In general a resource-defined style is more versatile and useful, and is more in keeping with the general [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] programming model principle of separating program logic in code from design in markup.
|
||||
The attribute usage is much more common. A style that is defined inline and not defined in resources is necessarily scoped to the containing element only, and cannot be re-used as easily because it has no resource key. In general a resource-defined style is more versatile and useful, and is more in keeping with the general Windows Presentation Foundation (WPF) programming model principle of separating program logic in code from design in markup.
|
||||
|
||||
Usually there is no reason to set a style or template inline, even if you only intend to use that style or template in that location. Most elements that can take a style or template also support a content property and a content model. If you are only using whatever logical tree you create through styling or templating once, it would be even easier to just fill that content property with the equivalent child elements in direct markup. This would bypass the style and template mechanisms altogether.
|
||||
|
||||
|
||||
@@ -27,11 +27,11 @@ helpviewer_keywords:
|
||||
ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef
|
||||
---
|
||||
# Input Overview
|
||||
<a name="introduction"></a> The [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] subsystem provides a powerful API for obtaining input from a variety of devices, including the mouse, keyboard, touch, and stylus. This topic describes the services provided by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and explains the architecture of the input systems.
|
||||
<a name="introduction"></a> The WPF and explains the architecture of the input systems.
|
||||
|
||||
<a name="input_api"></a>
|
||||
## Input API
|
||||
The primary input API exposure is found on the base element classes: <xref:System.Windows.UIElement>, <xref:System.Windows.ContentElement>, <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.FrameworkContentElement>. For more information about the base elements, see [Base Elements Overview](base-elements-overview.md). These classes provide functionality for input events related to key presses, mouse buttons, mouse wheel, mouse movement, focus management, and mouse capture, to name a few. By placing the input API on the base elements, rather than treating all input events as a service, the input architecture enables the input events to be sourced by a particular object in the UI, and to support an event routing scheme whereby more than one element has an opportunity to handle an input event. Many input events have a pair of events associated with them. For example, the key down event is associated with the <xref:System.Windows.Input.Keyboard.KeyDown> and <xref:System.Windows.Input.Keyboard.PreviewKeyDown> events. The difference in these events is in how they are routed to the target element. Preview events tunnel down the element tree from the root element to the target element. Bubbling events bubble up from the target element to the root element. Event routing in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is discussed in more detail later in this overview and in the [Routed Events Overview](routed-events-overview.md).
|
||||
The primary input API exposure is found on the base element classes: <xref:System.Windows.UIElement>, <xref:System.Windows.ContentElement>, <xref:System.Windows.FrameworkElement>, and <xref:System.Windows.FrameworkContentElement>. For more information about the base elements, see [Base Elements Overview](base-elements-overview.md). These classes provide functionality for input events related to key presses, mouse buttons, mouse wheel, mouse movement, focus management, and mouse capture, to name a few. By placing the input API on the base elements, rather than treating all input events as a service, the input architecture enables the input events to be sourced by a particular object in the UI, and to support an event routing scheme whereby more than one element has an opportunity to handle an input event. Many input events have a pair of events associated with them. For example, the key down event is associated with the <xref:System.Windows.Input.Keyboard.KeyDown> and <xref:System.Windows.Input.Keyboard.PreviewKeyDown> events. The difference in these events is in how they are routed to the target element. Preview events tunnel down the element tree from the root element to the target element. Bubbling events bubble up from the target element to the root element. Event routing in WPF is discussed in more detail later in this overview and in the [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
### Keyboard and Mouse Classes
|
||||
In addition to the input API on the base element classes, the <xref:System.Windows.Input.Keyboard> class and <xref:System.Windows.Input.Mouse> classes provide additional API for working with keyboard and mouse input.
|
||||
@@ -53,21 +53,21 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef
|
||||
The <xref:System.Windows.Input.Mouse> and <xref:System.Windows.Input.Keyboard> classes are covered in more detail throughout this overview.
|
||||
|
||||
### Stylus Input
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] has integrated support for the <xref:System.Windows.Input.Stylus>. The <xref:System.Windows.Input.Stylus> is a pen input made popular by the Tablet PC. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications can treat the stylus as a mouse by using the mouse API, but [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word "Stylus".
|
||||
WPF has integrated support for the <xref:System.Windows.Input.Stylus>. The <xref:System.Windows.Input.Stylus> is a pen input made popular by the Tablet PC. WPF applications can treat the stylus as a mouse by using the mouse API, but WPF also exposes a stylus device abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word "Stylus".
|
||||
|
||||
Because the stylus can act as a mouse, applications that support only mouse input can still obtain some level of stylus support automatically. When the stylus is used in such a manner, the application is given the opportunity to handle the appropriate stylus event and then handles the corresponding mouse event. In addition, higher-level services such as ink input are also available through the stylus device abstraction. For more information about ink as input, see [Getting Started with Ink](getting-started-with-ink.md).
|
||||
|
||||
<a name="event_routing"></a>
|
||||
## Event Routing
|
||||
A <xref:System.Windows.FrameworkElement> can contain other elements as child elements in its content model, forming a tree of elements. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the parent element can participate in input directed to its child elements or other descendants by handing events. This is especially useful for building controls out of smaller controls, a process known as "control composition" or "compositing." For more information about element trees and how element trees relate to event routes, see [Trees in WPF](trees-in-wpf.md).
|
||||
A <xref:System.Windows.FrameworkElement> can contain other elements as child elements in its content model, forming a tree of elements. In WPF, the parent element can participate in input directed to its child elements or other descendants by handing events. This is especially useful for building controls out of smaller controls, a process known as "control composition" or "compositing." For more information about element trees and how element trees relate to event routes, see [Trees in WPF](trees-in-wpf.md).
|
||||
|
||||
Event routing is the process of forwarding events to multiple elements, so that a particular object or element along the route can choose to offer a significant response (through handling) to an event that might have been sourced by a different element. Routed events use one of three routing mechanisms: direct, bubbling, and tunneling. In direct routing, the source element is the only element notified, and the event is not routed to any other elements. However, the direct routed event still offers some additional capabilities that are only present for routed events as opposed to standard CLR events. Bubbling works up the element tree by first notifying the element that sourced the event, then the parent element, and so on. Tunneling starts at the root of the element tree and works down, ending with the original source element. For more information about routed events, see [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input events generally come in pairs that consists of a tunneling event and a bubbling event. Tunneling events are distinguished from bubbling events with the "Preview" prefix. For instance, <xref:System.Windows.Input.Mouse.PreviewMouseMove> is the tunneling version of a mouse move event and <xref:System.Windows.Input.Mouse.MouseMove> is the bubbling version of this event. This event pairing is a convention that is implemented at the element level and is not an inherent capability of the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] event system. For details, see the WPF Input Events section in [Routed Events Overview](routed-events-overview.md).
|
||||
WPF input events generally come in pairs that consists of a tunneling event and a bubbling event. Tunneling events are distinguished from bubbling events with the "Preview" prefix. For instance, <xref:System.Windows.Input.Mouse.PreviewMouseMove> is the tunneling version of a mouse move event and <xref:System.Windows.Input.Mouse.MouseMove> is the bubbling version of this event. This event pairing is a convention that is implemented at the element level and is not an inherent capability of the WPF event system. For details, see the WPF Input Events section in [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
<a name="handling_input_events"></a>
|
||||
## Handling Input Events
|
||||
To receive input on an element, an event handler must be associated with that particular event. In [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] this is straightforward: you reference the name of the event as an attribute of the element that will be listening for this event. Then, you set the value of the attribute to the name of the event handler that you define, based on a delegate. The event handler must be written in code such as C# and can be included in a code-behind file.
|
||||
To receive input on an element, an event handler must be associated with that particular event. In XAML this is straightforward: you reference the name of the event as an attribute of the element that will be listening for this event. Then, you set the value of the attribute to the name of the event handler that you define, based on a delegate. The event handler must be written in code such as C# and can be included in a code-behind file.
|
||||
|
||||
Keyboard events occur when the operating system reports key actions that occur while keyboard focus is on an element. Mouse and stylus events each fall into two categories: events that report changes in pointer position relative to the element, and events that report changes in the state of device buttons.
|
||||
|
||||
@@ -108,9 +108,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef
|
||||
## Text Input
|
||||
The <xref:System.Windows.ContentElement.TextInput> event enables you to listen for text input in a device-independent manner. The keyboard is the primary means of text input, but speech, handwriting, and other input devices can generate text input also.
|
||||
|
||||
For keyboard input, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] first sends the appropriate <xref:System.Windows.ContentElement.KeyDown>/<xref:System.Windows.ContentElement.KeyUp> events. If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a <xref:System.Windows.ContentElement.TextInput> event is raised. There is not always a simple one-to-one mapping between <xref:System.Windows.ContentElement.KeyDown>/<xref:System.Windows.ContentElement.KeyUp> and <xref:System.Windows.ContentElement.TextInput> events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding alphabets.
|
||||
For keyboard input, WPF first sends the appropriate <xref:System.Windows.ContentElement.KeyDown>/<xref:System.Windows.ContentElement.KeyUp> events. If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a <xref:System.Windows.ContentElement.TextInput> event is raised. There is not always a simple one-to-one mapping between <xref:System.Windows.ContentElement.KeyDown>/<xref:System.Windows.ContentElement.KeyUp> and <xref:System.Windows.ContentElement.TextInput> events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding alphabets.
|
||||
|
||||
When [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] sends a <xref:System.Windows.ContentElement.KeyUp>/<xref:System.Windows.ContentElement.KeyDown> event, <xref:System.Windows.Input.KeyEventArgs.Key%2A> is set to <xref:System.Windows.Input.Key.System?displayProperty=nameWithType> if the keystrokes could become part of a <xref:System.Windows.ContentElement.TextInput> event (if ALT+S is pressed, for example). This allows code in a <xref:System.Windows.ContentElement.KeyDown> event handler to check for <xref:System.Windows.Input.Key.System?displayProperty=nameWithType> and, if found, leave processing for the handler of the subsequently raised <xref:System.Windows.ContentElement.TextInput> event. In these cases, the various properties of the <xref:System.Windows.Input.TextCompositionEventArgs> argument can be used to determine the original keystrokes. Similarly, if an IME is active, <xref:System.Windows.Input.Key> has the value of <xref:System.Windows.Input.Key.ImeProcessed?displayProperty=nameWithType>, and <xref:System.Windows.Input.KeyEventArgs.ImeProcessedKey%2A> gives the original keystroke or keystrokes.
|
||||
When WPF sends a <xref:System.Windows.ContentElement.KeyUp>/<xref:System.Windows.ContentElement.KeyDown> event, <xref:System.Windows.Input.KeyEventArgs.Key%2A> is set to <xref:System.Windows.Input.Key.System?displayProperty=nameWithType> if the keystrokes could become part of a <xref:System.Windows.ContentElement.TextInput> event (if ALT+S is pressed, for example). This allows code in a <xref:System.Windows.ContentElement.KeyDown> event handler to check for <xref:System.Windows.Input.Key.System?displayProperty=nameWithType> and, if found, leave processing for the handler of the subsequently raised <xref:System.Windows.ContentElement.TextInput> event. In these cases, the various properties of the <xref:System.Windows.Input.TextCompositionEventArgs> argument can be used to determine the original keystrokes. Similarly, if an IME is active, <xref:System.Windows.Input.Key> has the value of <xref:System.Windows.Input.Key.ImeProcessed?displayProperty=nameWithType>, and <xref:System.Windows.Input.KeyEventArgs.ImeProcessedKey%2A> gives the original keystroke or keystrokes.
|
||||
|
||||
The following example defines a handler for the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event and a handler for the <xref:System.Windows.UIElement.KeyDown> event.
|
||||
|
||||
@@ -132,9 +132,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef
|
||||
|
||||
<a name="touch_and_manipulation"></a>
|
||||
## Touch and Manipulation
|
||||
New hardware and API in the Windows 7 operating system provide applications the ability to receive input from multiple touches simultaneously. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables applications to detect and respond to touch in a manner similar to responding to other input, such as the mouse or keyboard, by raising events when touch occurs.
|
||||
New hardware and API in the Windows 7 operating system provide applications the ability to receive input from multiple touches simultaneously. WPF enables applications to detect and respond to touch in a manner similar to responding to other input, such as the mouse or keyboard, by raising events when touch occurs.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] exposes two types of events when touch occurs: touch events and manipulation events. Touch events provide raw data about each finger on a touchscreen and its movement. Manipulation events interpret the input as certain actions. Both types of events are discussed in this section.
|
||||
WPF exposes two types of events when touch occurs: touch events and manipulation events. Touch events provide raw data about each finger on a touchscreen and its movement. Manipulation events interpret the input as certain actions. Both types of events are discussed in this section.
|
||||
|
||||
### Prerequisites
|
||||
You need the following components to develop an application that responds to touch.
|
||||
@@ -150,9 +150,9 @@ ms.assetid: ee5258b7-6567-415a-9b1c-c0cbe46e79ef
|
||||
|
||||
- **Touch** is a type of user input that is recognized by Windows 7. Usually, touch is initiated by putting fingers on a touch-sensitive screen. Note that devices such as a touchpad that is common on laptop computers do not support touch if the device merely converts the finger's position and movement as mouse input.
|
||||
|
||||
- **Multitouch** is touch that occurs from more than one point simultaneously. Windows 7 and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] supports multitouch. Whenever touch is discussed in the documentation for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the concepts apply to multitouch.
|
||||
- **Multitouch** is touch that occurs from more than one point simultaneously. Windows 7 and WPF supports multitouch. Whenever touch is discussed in the documentation for WPF, the concepts apply to multitouch.
|
||||
|
||||
- A **manipulation** occurs when touch is interpreted as a physical action that is applied to an object. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], manipulation events interpret input as a translation, expansion, or rotation manipulation.
|
||||
- A **manipulation** occurs when touch is interpreted as a physical action that is applied to an object. In WPF, manipulation events interpret input as a translation, expansion, or rotation manipulation.
|
||||
|
||||
- A `touch device` represents a device that produces touch input, such as a single finger on a touchscreen.
|
||||
|
||||
@@ -236,7 +236,7 @@ Touch events
|
||||
|
||||
More than one type of manipulation can occur simultaneously.
|
||||
|
||||
When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can make your objects simulate the physical world. For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object.
|
||||
When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can make your objects simulate the physical world. For example, when you push a book across a table, if you push hard enough the book will continue to move after you release it. WPF enables you to simulate this behavior by raising manipulation events after the user's fingers releases the object.
|
||||
|
||||
For information about how to create an application that enables the user to move, resize, and rotate an object, see [Walkthrough: Creating Your First Touch Application](walkthrough-creating-your-first-touch-application.md).
|
||||
|
||||
@@ -274,7 +274,7 @@ Manipulation events
|
||||
|
||||
4. The <xref:System.Windows.UIElement.ManipulationInertiaStarting> event occurs when the user's fingers lose contact with the object. This event enables you to specify the deceleration of the manipulations during inertia. This is so your object can emulate different physical spaces or attributes if you choose. For example, suppose your application has two objects that represent items in the physical world, and one is heavier than the other. You can make the heavier object decelerate faster than the lighter object.
|
||||
|
||||
5. The <xref:System.Windows.UIElement.ManipulationDelta> event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] simulates inertia. In other words, <xref:System.Windows.UIElement.ManipulationDelta> occurs before and after the <xref:System.Windows.UIElement.ManipulationInertiaStarting> event. The <xref:System.Windows.Input.ManipulationDeltaEventArgs.IsInertial%2A?displayProperty=nameWithType> property reports whether the <xref:System.Windows.UIElement.ManipulationDelta> event occurs during inertia, so you can check that property and perform different actions, depending on its value.
|
||||
5. The <xref:System.Windows.UIElement.ManipulationDelta> event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when WPF simulates inertia. In other words, <xref:System.Windows.UIElement.ManipulationDelta> occurs before and after the <xref:System.Windows.UIElement.ManipulationInertiaStarting> event. The <xref:System.Windows.Input.ManipulationDeltaEventArgs.IsInertial%2A?displayProperty=nameWithType> property reports whether the <xref:System.Windows.UIElement.ManipulationDelta> event occurs during inertia, so you can check that property and perform different actions, depending on its value.
|
||||
|
||||
6. The <xref:System.Windows.UIElement.ManipulationCompleted> event occurs when the manipulation and any inertia ends. That is, after all the <xref:System.Windows.UIElement.ManipulationDelta> events occur, the <xref:System.Windows.UIElement.ManipulationCompleted> event occurs to signal that the manipulation is complete.
|
||||
|
||||
@@ -308,10 +308,10 @@ Touch and manipulation events
|
||||
|
||||
<a name="focus"></a>
|
||||
## Focus
|
||||
There are two main concepts that pertain to focus in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]: keyboard focus and logical focus.
|
||||
There are two main concepts that pertain to focus in WPF: keyboard focus and logical focus.
|
||||
|
||||
### Keyboard Focus
|
||||
Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the element that has keyboard focus will have <xref:System.Windows.IInputElement.IsKeyboardFocused%2A> set to `true`. The static <xref:System.Windows.Input.Keyboard> method <xref:System.Windows.Input.Keyboard.FocusedElement%2A> returns the element that currently has keyboard focus.
|
||||
Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have <xref:System.Windows.IInputElement.IsKeyboardFocused%2A> set to `true`. The static <xref:System.Windows.Input.Keyboard> method <xref:System.Windows.Input.Keyboard.FocusedElement%2A> returns the element that currently has keyboard focus.
|
||||
|
||||
Keyboard focus can be obtained by tabbing to an element or by clicking the mouse on certain elements, such as a <xref:System.Windows.Controls.TextBox>. Keyboard focus can also be obtained programmatically by using the <xref:System.Windows.Input.Keyboard.Focus%2A> method on the <xref:System.Windows.Input.Keyboard> class. <xref:System.Windows.Input.Keyboard.Focus%2A> attempts to give the specified element keyboard focus. The element returned by <xref:System.Windows.Input.Keyboard.Focus%2A> is the element that currently has keyboard focus.
|
||||
|
||||
@@ -329,7 +329,7 @@ Touch and manipulation events
|
||||
|
||||
A focus scope is a container element that keeps track of the <xref:System.Windows.Input.FocusManager.FocusedElement%2A> within its scope. When focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but insures that the focused element within the focus scope remains the focused element when focus returns.
|
||||
|
||||
An element can be turned into a focus scope in [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] by setting the <xref:System.Windows.Input.FocusManager> attached property <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> to `true`, or in code by setting the attached property by using the <xref:System.Windows.Input.FocusManager.SetIsFocusScope%2A> method.
|
||||
An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the <xref:System.Windows.Input.FocusManager> attached property <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> to `true`, or in code by setting the attached property by using the <xref:System.Windows.Input.FocusManager.SetIsFocusScope%2A> method.
|
||||
|
||||
The following example makes a <xref:System.Windows.Controls.StackPanel> into a focus scope by setting the <xref:System.Windows.Input.FocusManager.IsFocusScope%2A> attached property.
|
||||
|
||||
@@ -338,7 +338,7 @@ Touch and manipulation events
|
||||
[!code-csharp[FocusSnippets#FocusSetIsFocusScope](~/samples/snippets/csharp/VS_Snippets_Wpf/FocusSnippets/CSharp/Window1.xaml.cs#focussetisfocusscope)]
|
||||
[!code-vb[FocusSnippets#FocusSetIsFocusScope](~/samples/snippets/visualbasic/VS_Snippets_Wpf/FocusSnippets/visualbasic/window1.xaml.vb#focussetisfocusscope)]
|
||||
|
||||
Classes in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] which are focus scopes by default are <xref:System.Windows.Window>, <xref:System.Windows.Controls.Menu>, <xref:System.Windows.Controls.ToolBar>, and <xref:System.Windows.Controls.ContextMenu>.
|
||||
Classes in WPF which are focus scopes by default are <xref:System.Windows.Window>, <xref:System.Windows.Controls.Menu>, <xref:System.Windows.Controls.ToolBar>, and <xref:System.Windows.Controls.ContextMenu>.
|
||||
|
||||
An element that has keyboard focus will also have logical focus for the focus scope it belongs to; therefore, setting focus on an element with the <xref:System.Windows.Input.Keyboard.Focus%2A> method on the <xref:System.Windows.Input.Keyboard> class or the base element classes will attempt to give the element keyboard focus and logical focus.
|
||||
|
||||
@@ -348,7 +348,7 @@ Touch and manipulation events
|
||||
|
||||
<a name="mouse_position"></a>
|
||||
## Mouse Position
|
||||
The [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input API provides helpful information with regard to coordinate spaces. For example, coordinate `(0,0)` is the upper-left coordinate, but the upper-left of which element in the tree? The element that is the input target? The element you attached your event handler to? Or something else? To avoid confusion, the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] input API requires that you specify your frame of reference when you work with coordinates obtained through the mouse. The <xref:System.Windows.Input.Mouse.GetPosition%2A> method returns the coordinate of the mouse pointer relative to the specified element.
|
||||
The WPF input API provides helpful information with regard to coordinate spaces. For example, coordinate `(0,0)` is the upper-left coordinate, but the upper-left of which element in the tree? The element that is the input target? The element you attached your event handler to? Or something else? To avoid confusion, the WPF input API requires that you specify your frame of reference when you work with coordinates obtained through the mouse. The <xref:System.Windows.Input.Mouse.GetPosition%2A> method returns the coordinate of the mouse pointer relative to the specified element.
|
||||
|
||||
<a name="mouse_capture"></a>
|
||||
## Mouse Capture
|
||||
@@ -358,11 +358,11 @@ Touch and manipulation events
|
||||
## Commands
|
||||
Commands enable input handling at a more semantic level than device input. Commands are simple directives, such as `Cut`, `Copy`, `Paste`, or `Open`. Commands are useful for centralizing your command logic. The same command might be accessed from a <xref:System.Windows.Controls.Menu>, on a <xref:System.Windows.Controls.ToolBar>, or through a keyboard shortcut. Commands also provide a mechanism for disabling controls when the command becomes unavailable.
|
||||
|
||||
<xref:System.Windows.Input.RoutedCommand> is the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] implementation of <xref:System.Windows.Input.ICommand>. When a <xref:System.Windows.Input.RoutedCommand> is executed, a <xref:System.Windows.Input.CommandManager.PreviewExecuted> and an <xref:System.Windows.Input.CommandManager.Executed> event are raised on the command target, which tunnel and bubble through the element tree like other input. If a command target is not set, the element with keyboard focus will be the command target. The logic that performs the command is attached to a <xref:System.Windows.Input.CommandBinding>. When an <xref:System.Windows.Input.CommandManager.Executed> event reaches a <xref:System.Windows.Input.CommandBinding> for that specific command, the <xref:System.Windows.Input.ExecutedRoutedEventHandler> on the <xref:System.Windows.Input.CommandBinding> is called. This handler performs the action of the command.
|
||||
<xref:System.Windows.Input.RoutedCommand> is the WPF implementation of <xref:System.Windows.Input.ICommand>. When a <xref:System.Windows.Input.RoutedCommand> is executed, a <xref:System.Windows.Input.CommandManager.PreviewExecuted> and an <xref:System.Windows.Input.CommandManager.Executed> event are raised on the command target, which tunnel and bubble through the element tree like other input. If a command target is not set, the element with keyboard focus will be the command target. The logic that performs the command is attached to a <xref:System.Windows.Input.CommandBinding>. When an <xref:System.Windows.Input.CommandManager.Executed> event reaches a <xref:System.Windows.Input.CommandBinding> for that specific command, the <xref:System.Windows.Input.ExecutedRoutedEventHandler> on the <xref:System.Windows.Input.CommandBinding> is called. This handler performs the action of the command.
|
||||
|
||||
For more information on commanding, see [Commanding Overview](commanding-overview.md).
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] provides a library of common commands which consists of <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, and <xref:System.Windows.Documents.EditingCommands>, or you can define your own.
|
||||
WPF provides a library of common commands which consists of <xref:System.Windows.Input.ApplicationCommands>, <xref:System.Windows.Input.MediaCommands>, <xref:System.Windows.Input.ComponentCommands>, <xref:System.Windows.Input.NavigationCommands>, and <xref:System.Windows.Documents.EditingCommands>, or you can define your own.
|
||||
|
||||
The following example shows how to set up a <xref:System.Windows.Controls.MenuItem> so that when it is clicked it will invoke the <xref:System.Windows.Input.ApplicationCommands.Paste%2A> command on the <xref:System.Windows.Controls.TextBox>, assuming the <xref:System.Windows.Controls.TextBox> has keyboard focus.
|
||||
|
||||
@@ -371,7 +371,7 @@ Touch and manipulation events
|
||||
[!code-csharp[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/CommandingOverviewSnippets/CSharp/Window1.xaml.cs#commandingoverviewcommandtargetcodebehind)]
|
||||
[!code-vb[CommandingOverviewSnippets#CommandingOverviewCommandTargetCodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/CommandingOverviewSnippets/visualbasic/window1.xaml.vb#commandingoverviewcommandtargetcodebehind)]
|
||||
|
||||
For more information about commands in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], see [Commanding Overview](commanding-overview.md).
|
||||
For more information about commands in WPF, see [Commanding Overview](commanding-overview.md).
|
||||
|
||||
<a name="the_input_system_and_base_elements"></a>
|
||||
## The Input System and Base Elements
|
||||
@@ -379,13 +379,13 @@ Touch and manipulation events
|
||||
|
||||
Each of the events that <xref:System.Windows.Input.Mouse>, <xref:System.Windows.Input.Keyboard>, and <xref:System.Windows.Input.Stylus> define as an attached event is also re-exposed by the base element classes <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement> as a new routed event. The base element routed events are generated by classes handling the original attached event and reusing the event data.
|
||||
|
||||
When the input event becomes associated with a particular source element through its base element input event implementation, it can be routed through the remainder of an event route that is based on a combination of logical and visual tree objects, and be handled by application code. Generally, it is more convenient to handle these device-related input events using the routed events on <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>, because you can use more intuitive event handler syntax both in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and in code. You could choose to handle the attached event that initiated the process instead, but you would face several issues: the attached event may be marked handled by the base element class handling, and you need to use accessor methods rather than true event syntax in order to attach handlers for attached events.
|
||||
When the input event becomes associated with a particular source element through its base element input event implementation, it can be routed through the remainder of an event route that is based on a combination of logical and visual tree objects, and be handled by application code. Generally, it is more convenient to handle these device-related input events using the routed events on <xref:System.Windows.UIElement> and <xref:System.Windows.ContentElement>, because you can use more intuitive event handler syntax both in XAML and in code. You could choose to handle the attached event that initiated the process instead, but you would face several issues: the attached event may be marked handled by the base element class handling, and you need to use accessor methods rather than true event syntax in order to attach handlers for attached events.
|
||||
|
||||
<a name="whats_next"></a>
|
||||
## What's Next
|
||||
You now have several techniques to handle input in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. You should also have an improved understanding of the various types of input events and the routed event mechanisms used by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
|
||||
You now have several techniques to handle input in WPF. You should also have an improved understanding of the various types of input events and the routed event mechanisms used by WPF.
|
||||
|
||||
Additional resources are available that explain [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] framework elements and event routing in more detail. See the following overviews for more information, [Commanding Overview](commanding-overview.md), [Focus Overview](focus-overview.md), [Base Elements Overview](base-elements-overview.md), [Trees in WPF](trees-in-wpf.md), and [Routed Events Overview](routed-events-overview.md).
|
||||
Additional resources are available that explain WPF framework elements and event routing in more detail. See the following overviews for more information, [Commanding Overview](commanding-overview.md), [Focus Overview](focus-overview.md), [Base Elements Overview](base-elements-overview.md), [Trees in WPF](trees-in-wpf.md), and [Routed Events Overview](routed-events-overview.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
+6
-6
@@ -15,13 +15,13 @@ This topic describes the <xref:System.Windows.Media.GlyphRun> object and the <xr
|
||||
|
||||
<a name="text_glyphrunovw_intro"></a>
|
||||
## Introduction to GlyphRun
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides advanced text support including glyph-level markup with direct access to <xref:System.Windows.Documents.Glyphs> for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios.
|
||||
Windows Presentation Foundation (WPF) provides advanced text support including glyph-level markup with direct access to <xref:System.Windows.Documents.Glyphs> for customers who want to intercept and persist text after formatting. These features provide critical support for the different text rendering requirements in each of the following scenarios.
|
||||
|
||||
1. Screen display of fixed-format documents.
|
||||
|
||||
2. Print scenarios.
|
||||
|
||||
- [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] as a device printer language.
|
||||
- Extensible Application Markup Language (XAML) as a device printer language.
|
||||
|
||||
- Microsoft XPS Document Writer.
|
||||
|
||||
@@ -32,7 +32,7 @@ This topic describes the <xref:System.Windows.Media.GlyphRun> object and the <xr
|
||||
3. Fixed-format document representation, including clients for previous versions of Windows and other computing devices.
|
||||
|
||||
> [!NOTE]
|
||||
> <xref:System.Windows.Documents.Glyphs> and <xref:System.Windows.Media.GlyphRun> are designed for fixed-format document presentation and print scenarios. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] provides several elements for general layout and [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] scenarios such as <xref:System.Windows.Controls.Label> and <xref:System.Windows.Controls.TextBlock>. For more information on layout and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] scenarios, see the [Typography in WPF](typography-in-wpf.md).
|
||||
> <xref:System.Windows.Documents.Glyphs> and <xref:System.Windows.Media.GlyphRun> are designed for fixed-format document presentation and print scenarios. UI scenarios, see the [Typography in WPF](typography-in-wpf.md).
|
||||
|
||||
<a name="text_glyphrunovw_glyphrunobject"></a>
|
||||
## The GlyphRun Object
|
||||
@@ -40,11 +40,11 @@ This topic describes the <xref:System.Windows.Media.GlyphRun> object and the <xr
|
||||
|
||||
<xref:System.Windows.Media.GlyphRun> includes both font details such as glyph <xref:System.Windows.Documents.Glyphs.Indices%2A> and individual glyph positions. It also includes the original Unicode code points the run was generated from, character-to-glyph buffer offset mapping information, and per-character and per-glyph flags.
|
||||
|
||||
<xref:System.Windows.Media.GlyphRun> has a corresponding high-level <xref:System.Windows.FrameworkElement>, <xref:System.Windows.Documents.Glyphs>. <xref:System.Windows.Documents.Glyphs> can be used in the element tree and in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup to represent <xref:System.Windows.Media.GlyphRun> output.
|
||||
<xref:System.Windows.Media.GlyphRun> has a corresponding high-level <xref:System.Windows.FrameworkElement>, <xref:System.Windows.Documents.Glyphs>. <xref:System.Windows.Documents.Glyphs> can be used in the element tree and in XAML markup to represent <xref:System.Windows.Media.GlyphRun> output.
|
||||
|
||||
<a name="text_glyphrunovw_glyphselement"></a>
|
||||
## The Glyphs Element
|
||||
The <xref:System.Windows.Documents.Glyphs> element represents the output of a <xref:System.Windows.Media.GlyphRun> in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)]. The following markup syntax is used to describe the <xref:System.Windows.Documents.Glyphs> element.
|
||||
The <xref:System.Windows.Documents.Glyphs> element represents the output of a <xref:System.Windows.Media.GlyphRun> in XAML. The following markup syntax is used to describe the <xref:System.Windows.Documents.Glyphs> element.
|
||||
|
||||
[!code-xaml[GlyphsOvwSample1#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSample1/CS/default.xaml#1)]
|
||||
|
||||
@@ -83,7 +83,7 @@ This topic describes the <xref:System.Windows.Media.GlyphRun> object and the <xr
|
||||
|
||||
<a name="text_glyphrunovw_glyphsmarkup"></a>
|
||||
## Glyphs Markup
|
||||
The following code example shows how to use various properties of the <xref:System.Windows.Documents.Glyphs> element in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
|
||||
The following code example shows how to use various properties of the <xref:System.Windows.Documents.Glyphs> element in XAML.
|
||||
|
||||
[!code-xaml[GlyphsOvwSamp2#1](~/samples/snippets/csharp/VS_Snippets_Wpf/GlyphsOvwSamp2/CS/default.xaml#1)]
|
||||
|
||||
|
||||
+15
-15
@@ -11,14 +11,14 @@ helpviewer_keywords:
|
||||
ms.assetid: 3c574597-bbde-440f-95cc-01371f1a5d9d
|
||||
---
|
||||
# Layout Considerations for the WindowsFormsHost Element
|
||||
This topic describes how the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element interacts with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system.
|
||||
This topic describes how the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element interacts with the WPF layout system.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms support different, but similar, logic for sizing and positioning elements on a form or page. When you create a hybrid user interface (UI) that hosts Windows Forms controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)], the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element integrates the two layout schemes.
|
||||
WPF and Windows Forms support different, but similar, logic for sizing and positioning elements on a form or page. When you create a hybrid user interface (UI) that hosts Windows Forms controls in WPF, the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element integrates the two layout schemes.
|
||||
|
||||
## Differences in Layout Between WPF and Windows Forms
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] uses resolution-independent layout. All [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout dimensions are specified using *device-independent pixels*. A device-independent pixel is one ninety-sixth of an inch in size and resolution-independent, so you get similar results regardless of whether you are rendering to a 72-dpi monitor or a 19,200-dpi printer.
|
||||
WPF uses resolution-independent layout. All WPF layout dimensions are specified using *device-independent pixels*. A device-independent pixel is one ninety-sixth of an inch in size and resolution-independent, so you get similar results regardless of whether you are rendering to a 72-dpi monitor or a 19,200-dpi printer.
|
||||
|
||||
[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] is also based on *dynamic layout*. This means that a UI element arranges itself on a form or page according to its content, its parent layout container, and the available screen size. Dynamic layout facilitates localization by automatically adjusting the size and position of UI elements when the strings they contain change length.
|
||||
WPF is also based on *dynamic layout*. This means that a UI element arranges itself on a form or page according to its content, its parent layout container, and the available screen size. Dynamic layout facilitates localization by automatically adjusting the size and position of UI elements when the strings they contain change length.
|
||||
|
||||
Layout in Windows Forms is device-dependent and more likely to be static. Typically, Windows Forms controls are positioned absolutely on a form using dimensions specified in hardware pixels. However, Windows Forms does support some dynamic layout features, as summarized in the following table.
|
||||
|
||||
@@ -30,26 +30,26 @@ This topic describes how the <xref:System.Windows.Forms.Integration.WindowsForms
|
||||
|Layout containers|The <xref:System.Windows.Forms.FlowLayoutPanel> and <xref:System.Windows.Forms.TableLayoutPanel> controls arrange their child controls and size themselves according to their contents.|
|
||||
|
||||
## Layout Limitations
|
||||
In general, Windows Forms controls cannot be scaled and transformed to the extent possible in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]. The following list describes the known limitations when the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element attempts to integrate its hosted Windows Forms control into the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system.
|
||||
In general, Windows Forms controls cannot be scaled and transformed to the extent possible in WPF. The following list describes the known limitations when the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element attempts to integrate its hosted Windows Forms control into the WPF layout system.
|
||||
|
||||
- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms <xref:System.Windows.Forms.ComboBox> control supports only a single height, which is defined by the control's font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] dynamic layout where elements can stretch vertically, a hosted <xref:System.Windows.Forms.ComboBox> control will not stretch as expected.
|
||||
- In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For example, a Windows Forms <xref:System.Windows.Forms.ComboBox> control supports only a single height, which is defined by the control's font size. In a WPF dynamic layout where elements can stretch vertically, a hosted <xref:System.Windows.Forms.ComboBox> control will not stretch as expected.
|
||||
|
||||
- Windows Forms controls cannot be rotated or skewed. The <xref:System.Windows.Forms.Integration.WindowsFormsHost> element raises the <xref:System.Windows.Forms.Integration.WindowsFormsHost.LayoutError> event if you apply a skew or rotation transformation. If you do not handle the <xref:System.Windows.Forms.Integration.WindowsFormsHost.LayoutError> event, an <xref:System.InvalidOperationException> is raised.
|
||||
|
||||
- In most cases, Windows Forms controls do not support proportional scaling. Although the overall dimensions of the control will scale, child controls and component elements of the control may not resize as expected. This limitation depends on how well each Windows Forms control supports scaling. In addition, you cannot scale Windows Forms controls down to a size of 0 pixels.
|
||||
|
||||
- Windows Forms controls support autoscaling, in which the form will automatically resize itself and its controls based on the font size. In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize.
|
||||
- Windows Forms controls support autoscaling, in which the form will automatically resize itself and its controls based on the font size. In a WPF user interface, changing the font size does not resize the entire layout, although individual elements may dynamically resize.
|
||||
|
||||
### Z-order
|
||||
In a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements.
|
||||
In a WPF user interface, you can change the z-order of elements to control overlapping behavior. A hosted Windows Forms control is drawn in a separate HWND, so it is always drawn on top of WPF elements.
|
||||
|
||||
A hosted Windows Forms control is also drawn on top of any <xref:System.Windows.Documents.Adorner> elements.
|
||||
|
||||
## Layout Behavior
|
||||
The following sections describe specific aspects of layout behavior when hosting Windows Forms controls in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)].
|
||||
The following sections describe specific aspects of layout behavior when hosting Windows Forms controls in WPF.
|
||||
|
||||
### Scaling, Unit Conversion, and Device Independence
|
||||
Whenever the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element performs operations involving [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and Windows Forms dimensions, two coordinate systems are involved: device-independent pixels for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and hardware pixels for Windows Forms. Therefore, you must apply proper unit and scaling conversions to achieve a consistent layout.
|
||||
Whenever the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element performs operations involving WPF and Windows Forms dimensions, two coordinate systems are involved: device-independent pixels for WPF and hardware pixels for Windows Forms. Therefore, you must apply proper unit and scaling conversions to achieve a consistent layout.
|
||||
|
||||
Conversion between the coordinate systems depends on the current device resolution and any layout or rendering transforms applied to the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element or to its ancestors.
|
||||
|
||||
@@ -63,17 +63,17 @@ This topic describes how the <xref:System.Windows.Forms.Integration.WindowsForms
|
||||
|
||||
|Conversion issue|Description|
|
||||
|----------------------|-----------------|
|
||||
|Rounding|[!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] device-independent pixel dimensions are specified as `double`, and Windows Forms hardware pixel dimensions are specified as `int`. In cases where `double`-based dimensions are converted to `int`-based dimensions, the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element uses standard rounding, so that fractional values less than 0.5 are rounded down to 0.|
|
||||
|Rounding|WPF device-independent pixel dimensions are specified as `double`, and Windows Forms hardware pixel dimensions are specified as `int`. In cases where `double`-based dimensions are converted to `int`-based dimensions, the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element uses standard rounding, so that fractional values less than 0.5 are rounded down to 0.|
|
||||
|Overflow|When the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element converts from `double` values to `int` values, overflow is possible. Values that are larger than <xref:System.Int32.MaxValue> are set to <xref:System.Int32.MaxValue>.|
|
||||
|
||||
### Layout-related Properties
|
||||
Properties that control layout behavior in Windows Forms controls and [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] elements are mapped appropriately by the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md).
|
||||
Properties that control layout behavior in Windows Forms controls and WPF elements are mapped appropriately by the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element. For more information, see [Windows Forms and WPF Property Mapping](windows-forms-and-wpf-property-mapping.md).
|
||||
|
||||
### Layout Changes in the Hosted Control
|
||||
Layout changes in the hosted Windows Forms control are propagated to [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] to trigger layout updates. The <xref:System.Windows.UIElement.InvalidateMeasure%2A> method on <xref:System.Windows.Forms.Integration.WindowsFormsHost> ensures that layout changes in the hosted control cause the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout engine to run.
|
||||
Layout changes in the hosted Windows Forms control are propagated to WPF to trigger layout updates. The <xref:System.Windows.UIElement.InvalidateMeasure%2A> method on <xref:System.Windows.Forms.Integration.WindowsFormsHost> ensures that layout changes in the hosted control cause the WPF layout engine to run.
|
||||
|
||||
### Continuously Sized Windows Forms Controls
|
||||
Windows Forms controls that support continuous scaling fully interact with the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system. The <xref:System.Windows.Forms.Integration.WindowsFormsHost> element uses the <xref:System.Windows.FrameworkElement.MeasureOverride%2A> and <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> methods as usual to size and arrange the hosted Windows Forms control.
|
||||
Windows Forms controls that support continuous scaling fully interact with the WPF layout system. The <xref:System.Windows.Forms.Integration.WindowsFormsHost> element uses the <xref:System.Windows.FrameworkElement.MeasureOverride%2A> and <xref:System.Windows.FrameworkElement.ArrangeOverride%2A> methods as usual to size and arrange the hosted Windows Forms control.
|
||||
|
||||
### Sizing Algorithm
|
||||
The <xref:System.Windows.Forms.Integration.WindowsFormsHost> element uses the following procedure to size the hosted control:
|
||||
@@ -90,7 +90,7 @@ This topic describes how the <xref:System.Windows.Forms.Integration.WindowsForms
|
||||
|
||||
- If the <xref:System.Windows.Forms.Control.Size%2A> property returns a larger size than the specified constraint, the <xref:System.Windows.Forms.Integration.WindowsFormsHost> element clips the hosted control. Height and width are handled separately, so the hosted control may be clipped in either direction.
|
||||
|
||||
- If the <xref:System.Windows.Forms.Control.Size%2A> property returns a smaller size than the specified constraint, <xref:System.Windows.Forms.Integration.WindowsFormsHost> accepts this size value and returns the value to the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] layout system.
|
||||
- If the <xref:System.Windows.Forms.Control.Size%2A> property returns a smaller size than the specified constraint, <xref:System.Windows.Forms.Integration.WindowsFormsHost> accepts this size value and returns the value to the WPF layout system.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ The following illustration shows a simple layout.
|
||||
|
||||

|
||||
|
||||
This layout can be achieved by using the following [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)].
|
||||
This layout can be achieved by using the following XAML.
|
||||
|
||||
[!code-xaml[LayoutInformation#1](~/samples/snippets/csharp/VS_Snippets_Wpf/LayoutInformation/CSharp/Window1.xaml#1)]
|
||||
|
||||
@@ -133,7 +133,7 @@ Layout is a recursive process. Each child element in a <xref:System.Windows.Cont
|
||||
|
||||
- When possible, use a <xref:System.Windows.UIElement.RenderTransform%2A> instead of a <xref:System.Windows.FrameworkElement.LayoutTransform%2A>.
|
||||
|
||||
A <xref:System.Windows.FrameworkElement.LayoutTransform%2A> can be a very useful way to affect the content of a [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)]. However, if the effect of the transform does not have to impact the position of other elements, it is best to use a <xref:System.Windows.UIElement.RenderTransform%2A> instead, because <xref:System.Windows.UIElement.RenderTransform%2A> does not invoke the layout system. <xref:System.Windows.FrameworkElement.LayoutTransform%2A> applies its transformation and forces a recursive layout update to account for the new position of the affected element.
|
||||
A <xref:System.Windows.FrameworkElement.LayoutTransform%2A> can be a very useful way to affect the content of a user interface (UI). However, if the effect of the transform does not have to impact the position of other elements, it is best to use a <xref:System.Windows.UIElement.RenderTransform%2A> instead, because <xref:System.Windows.UIElement.RenderTransform%2A> does not invoke the layout system. <xref:System.Windows.FrameworkElement.LayoutTransform%2A> applies its transformation and forces a recursive layout update to account for the new position of the affected element.
|
||||
|
||||
- Avoid unnecessary calls to <xref:System.Windows.UIElement.UpdateLayout%2A>.
|
||||
|
||||
|
||||
+1
-1
@@ -40,7 +40,7 @@ HRESULT LoadFromHistory_export(
|
||||
|
||||
In the .NET Framework 4 and later: PresentationHost_v0400.dll
|
||||
|
||||
**.NET Framework Version:** [!INCLUDE[net_current_v30plus](../../../includes/net-current-v30plus-md.md)]
|
||||
**.NET Framework Version:** Available since 3.0
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ helpviewer_keywords:
|
||||
ms.assetid: ead2d9ac-b709-4ec1-a924-39927a29d02f
|
||||
---
|
||||
# Localization Attributes and Comments
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] localization comments are properties, inside XAML source code, supplied by developers to provide rules and hints for localization. [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] localization comments contain two sets of information: localizability attributes and free-form localization comments. Localizability attributes are used by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] Localization API to indicate which resources are to be localized. Free-form comments are any information that the application author wants to include.
|
||||
WPF Localization API to indicate which resources are to be localized. Free-form comments are any information that the application author wants to include.
|
||||
|
||||
<a name="Localizer_Comments_"></a>
|
||||
## Add Localization Comments
|
||||
|
||||
+7
-7
@@ -27,23 +27,23 @@ Handlers for a routed event can mark the event handled within the event data. Ha
|
||||
|
||||
<a name="When_to_Mark_Events_as_Handled"></a>
|
||||
## When to Mark Events as Handled
|
||||
When you set the value of the <xref:System.Windows.RoutedEventArgs.Handled%2A> property to `true` in the event data for a routed event, this is referred to as "marking the event handled". There is no absolute rule for when you should mark routed events as handled, either as an application author, or as a control author who responds to existing routed events or implements new routed events. For the most part, the concept of "handled" as carried in the routed event's event data should be used as a limited protocol for your own application's responses to the various routed events exposed in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] APIs as well as for any custom routed events. Another way to consider the "handled" issue is that you should generally mark a routed event handled if your code responded to the routed event in a significant and relatively complete way. Typically, there should not be more than one significant response that requires separate handler implementations for any single routed event occurrence. If more responses are needed, then the necessary code should be implemented through application logic that is chained within a single handler rather than by using the routed event system for forwarding. The concept of what is "significant" is also subjective, and depends on your application or code. As general guidance, some "significant response" examples include: setting focus, modifying public state, setting properties that affect the visual representation, and raising other new events. Examples of nonsignificant responses include: modifying private state (with no visual impact, or programmatic representation), logging of events, or looking at arguments of an event and choosing not to respond to it.
|
||||
When you set the value of the <xref:System.Windows.RoutedEventArgs.Handled%2A> property to `true` in the event data for a routed event, this is referred to as "marking the event handled". There is no absolute rule for when you should mark routed events as handled, either as an application author, or as a control author who responds to existing routed events or implements new routed events. For the most part, the concept of "handled" as carried in the routed event's event data should be used as a limited protocol for your own application's responses to the various routed events exposed in WPF APIs as well as for any custom routed events. Another way to consider the "handled" issue is that you should generally mark a routed event handled if your code responded to the routed event in a significant and relatively complete way. Typically, there should not be more than one significant response that requires separate handler implementations for any single routed event occurrence. If more responses are needed, then the necessary code should be implemented through application logic that is chained within a single handler rather than by using the routed event system for forwarding. The concept of what is "significant" is also subjective, and depends on your application or code. As general guidance, some "significant response" examples include: setting focus, modifying public state, setting properties that affect the visual representation, and raising other new events. Examples of nonsignificant responses include: modifying private state (with no visual impact, or programmatic representation), logging of events, or looking at arguments of an event and choosing not to respond to it.
|
||||
|
||||
The routed event system behavior reinforces this "significant response" model for using handled state of a routed event, because handlers added in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] or the common signature of <xref:System.Windows.UIElement.AddHandler%2A> are not invoked in response to a routed event where the event data is already marked handled. You must go through the extra effort of adding a handler with the `handledEventsToo` parameter version (<xref:System.Windows.UIElement.AddHandler%28System.Windows.RoutedEvent%2CSystem.Delegate%2CSystem.Boolean%29>) in order to handle routed events that are marked handled by earlier participants in the event route.
|
||||
The routed event system behavior reinforces this "significant response" model for using handled state of a routed event, because handlers added in XAML or the common signature of <xref:System.Windows.UIElement.AddHandler%2A> are not invoked in response to a routed event where the event data is already marked handled. You must go through the extra effort of adding a handler with the `handledEventsToo` parameter version (<xref:System.Windows.UIElement.AddHandler%28System.Windows.RoutedEvent%2CSystem.Delegate%2CSystem.Boolean%29>) in order to handle routed events that are marked handled by earlier participants in the event route.
|
||||
|
||||
In some circumstances, controls themselves mark certain routed events as handled. A handled routed event represents a decision by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] control authors that the control's actions in response to the routed event are significant or complete as part of the control implementation, and the event needs no further handling. Usually this is done by adding a class handler for an event, or by overriding one of the class handler virtuals that exist on a base class. You can still work around this event handling if necessary; see [Working Around Event Suppression by Controls](#WorkingAroundEventSuppressionByControls) later in this topic.
|
||||
In some circumstances, controls themselves mark certain routed events as handled. A handled routed event represents a decision by WPF control authors that the control's actions in response to the routed event are significant or complete as part of the control implementation, and the event needs no further handling. Usually this is done by adding a class handler for an event, or by overriding one of the class handler virtuals that exist on a base class. You can still work around this event handling if necessary; see [Working Around Event Suppression by Controls](#WorkingAroundEventSuppressionByControls) later in this topic.
|
||||
|
||||
<a name="Preview_Events_vs__Bubbling_Events_and_Handling"></a>
|
||||
## "Preview" (Tunneling) Events vs. Bubbling Events, and Event Handling
|
||||
Preview routed events are events that follow a tunneling route through the element tree. The "Preview" expressed in the naming convention is indicative of the general principle for input events that preview (tunneling) routed events are raised prior to the equivalent bubbling routed event. Also, input routed events that have a tunneling and bubbling pair have a distinct handling logic. If the tunneling/preview routed event is marked as handled by an event listener, then the bubbling routed event will be marked handled even before any listeners of the bubbling routed event receive it. The tunneling and bubbling routed events are technically separate events, but they deliberately share the same instance of event data to enable this behavior.
|
||||
|
||||
The connection between the tunneling and bubbling routed events is accomplished by the internal implementation of how any given [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] class raises its own declared routed events, and this is true of the paired input routed events. But unless this class-level implementation exists, there is no connection between a tunneling routed event and a bubbling routed event that share the naming scheme: without such implementation they would be two entirely separate routed events and would not be raised in sequence or share event data.
|
||||
The connection between the tunneling and bubbling routed events is accomplished by the internal implementation of how any given WPF class raises its own declared routed events, and this is true of the paired input routed events. But unless this class-level implementation exists, there is no connection between a tunneling routed event and a bubbling routed event that share the naming scheme: without such implementation they would be two entirely separate routed events and would not be raised in sequence or share event data.
|
||||
|
||||
For more information about how to implement tunnel/bubble input routed event pairs in a custom class, see [Create a Custom Routed Event](how-to-create-a-custom-routed-event.md).
|
||||
|
||||
<a name="Class_Handlers_and_Instance_Handlers"></a>
|
||||
## Class Handlers and Instance Handlers
|
||||
Routed events consider two different types of listeners to the event: class listeners and instance listeners. Class listeners exist because types have called a particular <xref:System.Windows.EventManager> API ,<xref:System.Windows.EventManager.RegisterClassHandler%2A>, in their static constructor, or have overridden a class handler virtual method from an element base class. Instance listeners are particular class instances/elements where one or more handlers have been attached for that routed event by a call to <xref:System.Windows.UIElement.AddHandler%2A>. Existing [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] routed events make calls to <xref:System.Windows.UIElement.AddHandler%2A> as part of the common language runtime (CLR) event wrapper add{} and remove{} implementations of the event, which is also how the simple [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] mechanism of attaching event handlers via an attribute syntax is enabled. Therefore even the simple [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] usage ultimately equates to an <xref:System.Windows.UIElement.AddHandler%2A> call.
|
||||
Routed events consider two different types of listeners to the event: class listeners and instance listeners. Class listeners exist because types have called a particular <xref:System.Windows.EventManager> API ,<xref:System.Windows.EventManager.RegisterClassHandler%2A>, in their static constructor, or have overridden a class handler virtual method from an element base class. Instance listeners are particular class instances/elements where one or more handlers have been attached for that routed event by a call to <xref:System.Windows.UIElement.AddHandler%2A>. Existing WPF routed events make calls to <xref:System.Windows.UIElement.AddHandler%2A> as part of the common language runtime (CLR) event wrapper add{} and remove{} implementations of the event, which is also how the simple XAML mechanism of attaching event handlers via an attribute syntax is enabled. Therefore even the simple XAML usage ultimately equates to an <xref:System.Windows.UIElement.AddHandler%2A> call.
|
||||
|
||||
Elements within the visual tree are checked for registered handler implementations. Handlers are potentially invoked throughout the route, in the order that is inherent in the type of the routing strategy for that routed event. For instance, bubbling routed events will first invoke those handlers that are attached to the same element that raised the routed event. Then the routed event "bubbles" to the next parent element and so on until the application root element is reached.
|
||||
|
||||
@@ -78,7 +78,7 @@ Handlers for a routed event can mark the event handled within the event data. Ha
|
||||
|
||||
<a name="Deliberately_Suppressing_Input_Events_for_Control"></a>
|
||||
## Deliberately Suppressing Input Events for Control Compositing
|
||||
The main scenario where class handling of routed events is used is for input events and composited controls. A composited control is by definition composed of multiple practical controls or control base classes. Often the author of the control wishes to amalgamate all of the possible input events that each of the subcomponents might raise, in order to report the entire control as the singular event source. In some cases the control author might wish to suppress the events from components entirely, or substitute a component-defined event that carries more information or implies a more specific behavior. The canonical example that is immediately visible to any component author is how a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] <xref:System.Windows.Controls.Button> handles any mouse event that will eventually resolve to the intuitive event that all buttons have: a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event.
|
||||
The main scenario where class handling of routed events is used is for input events and composited controls. A composited control is by definition composed of multiple practical controls or control base classes. Often the author of the control wishes to amalgamate all of the possible input events that each of the subcomponents might raise, in order to report the entire control as the singular event source. In some cases the control author might wish to suppress the events from components entirely, or substitute a component-defined event that carries more information or implies a more specific behavior. The canonical example that is immediately visible to any component author is how a Windows Presentation Foundation (WPF) <xref:System.Windows.Controls.Button> handles any mouse event that will eventually resolve to the intuitive event that all buttons have: a <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event.
|
||||
|
||||
The <xref:System.Windows.Controls.Button> base class (<xref:System.Windows.Controls.Primitives.ButtonBase>) derives from <xref:System.Windows.Controls.Control> which in turn derives from <xref:System.Windows.FrameworkElement> and <xref:System.Windows.UIElement>, and much of the event infrastructure needed for control input processing is available at the <xref:System.Windows.UIElement> level. In particular, <xref:System.Windows.UIElement> processes general <xref:System.Windows.Input.Mouse> events that handle hit testing for the mouse cursor within its bounds, and provides distinct events for the most common button actions, such as <xref:System.Windows.UIElement.MouseLeftButtonDown>. <xref:System.Windows.UIElement> also provides an empty virtual <xref:System.Windows.UIElement.OnMouseLeftButtonDown%2A> as the preregistered class handler for <xref:System.Windows.UIElement.MouseLeftButtonDown>, and <xref:System.Windows.Controls.Primitives.ButtonBase> overrides it. Similarly, <xref:System.Windows.Controls.Primitives.ButtonBase> uses class handlers for <xref:System.Windows.UIElement.MouseLeftButtonUp>. In the overrides, which are passed the event data, the implementations mark that <xref:System.Windows.RoutedEventArgs> instance as handled by setting <xref:System.Windows.RoutedEventArgs.Handled%2A> to `true`, and that same event data is what continues along the remainder of the route to other class handlers and also to instance handlers or event setters. Also, the <xref:System.Windows.Controls.Primitives.ButtonBase.OnMouseLeftButtonUp%2A> override will next raise the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event. The end result for most listeners will be that the <xref:System.Windows.UIElement.MouseLeftButtonDown> and <xref:System.Windows.UIElement.MouseLeftButtonUp> events "disappear" and are replaced instead by <xref:System.Windows.Controls.Primitives.ButtonBase.Click>, an event that holds more meaning because it is known that this event originated from a true button and not some composite piece of the button or from some other element entirely.
|
||||
|
||||
@@ -86,7 +86,7 @@ Handlers for a routed event can mark the event handled within the event data. Ha
|
||||
### Working Around Event Suppression by Controls
|
||||
Sometimes this event suppression behavior within individual controls can interfere with some more general intentions of event handling logic for your application. For instance, if for some reason your application had a handler for <xref:System.Windows.UIElement.MouseLeftButtonDown> located at the application root element, you would notice that any mouse click on a button would not invoke <xref:System.Windows.UIElement.MouseLeftButtonDown> or <xref:System.Windows.UIElement.MouseLeftButtonUp> handlers at the root level. The event itself actually did bubble up (again, event routes are not truly ended, but the routed event system changes their handler invocation behavior after being marked handled). When the routed event reached the button, the <xref:System.Windows.Controls.Primitives.ButtonBase> class handling marked the <xref:System.Windows.UIElement.MouseLeftButtonDown> handled because it wished to substitute the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event with more meaning. Therefore, any standard <xref:System.Windows.UIElement.MouseLeftButtonDown> handler further up the route would not be invoked. There are two techniques you can use to ensure that your handlers would be invoked in this circumstance.
|
||||
|
||||
The first technique is to deliberately add the handler using the `handledEventsToo` signature of <xref:System.Windows.UIElement.AddHandler%28System.Windows.RoutedEvent%2CSystem.Delegate%2CSystem.Boolean%29>. A limitation of this approach is that this technique for attaching an event handler is only possible from code, not from markup. The simple syntax of specifying the event handler name as an event attribute value via [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] does not enable that behavior.
|
||||
The first technique is to deliberately add the handler using the `handledEventsToo` signature of <xref:System.Windows.UIElement.AddHandler%28System.Windows.RoutedEvent%2CSystem.Delegate%2CSystem.Boolean%29>. A limitation of this approach is that this technique for attaching an event handler is only possible from code, not from markup. The simple syntax of specifying the event handler name as an event attribute value via Extensible Application Markup Language (XAML) does not enable that behavior.
|
||||
|
||||
The second technique works only for input events, where the tunneling and bubbling versions of the routed event are paired. For these routed events, you can add handlers to the preview/tunneling equivalent routed event instead. That routed event will tunnel through the route starting from the root, so the button class handling code would not intercept it, presuming that you attached the Preview handler at some ancestor element level in the application's element tree. If you use this approach, be cautious about marking any Preview event handled. For the example given with <xref:System.Windows.UIElement.PreviewMouseLeftButtonDown> being handled at the root element, if you marked the event as <xref:System.Windows.RoutedEventArgs.Handled%2A> in the handler implementation, you would actually suppress the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event. That is typically not desirable behavior.
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ helpviewer_keywords:
|
||||
ms.assetid: acd9a6ef-b7ca-4146-abb6-60f3b366e9ec
|
||||
---
|
||||
# mc:Ignorable Attribute
|
||||
Specifies which XML namespace prefixes encountered in a markup file may be ignored by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor. The `mc:Ignorable` attribute supports markup compatibility both for custom namespace mapping and for [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] versioning.
|
||||
Specifies which XML namespace prefixes encountered in a markup file may be ignored by a XAML processor. The `mc:Ignorable` attribute supports markup compatibility both for custom namespace mapping and for XAML versioning.
|
||||
|
||||
## XAML Attribute Usage (Single Prefix)
|
||||
|
||||
@@ -44,18 +44,18 @@ Specifies which XML namespace prefixes encountered in a markup file may be ignor
|
||||
|-------|-------------|
|
||||
|*ignorablePrefix, ignorablePrefix1, etc.*|Any valid prefix string, per the XML 1.0 specification.|
|
||||
|*ignorableUri*|Any valid URI for designating a namespace, per the XML 1.0 specification.|
|
||||
|*ThisElementCanBeIgnored*|An element that can be ignored by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] processor implementations, if the underlying type cannot be resolved.|
|
||||
|*ThisElementCanBeIgnored*|An element that can be ignored by Extensible Application Markup Language (XAML) processor implementations, if the underlying type cannot be resolved.|
|
||||
|
||||
## Remarks
|
||||
The `mc` XML namespace prefix is the recommended prefix convention to use when mapping the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] compatibility namespace `http://schemas.openxmlformats.org/markup-compatibility/2006`.
|
||||
The `mc` XML namespace prefix is the recommended prefix convention to use when mapping the XAML compatibility namespace `http://schemas.openxmlformats.org/markup-compatibility/2006`.
|
||||
|
||||
Elements or attributes where the prefix portion of the element name are identified as `mc:Ignorable` will not raise errors when processed by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor. If that attribute could not be resolved to an underlying type or programming construct, then that element is ignored. Note however that ignored elements might still generate additional parsing errors for additional element requirements that are side effects of that element not being processed. For instance, a particular element content model might require exactly one child element, but if the specified child element was in an `mc:Ignorable` prefix, and the specified child element could not be resolved to a type, then the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor might raise an error.
|
||||
Elements or attributes where the prefix portion of the element name are identified as `mc:Ignorable` will not raise errors when processed by a XAML processor. If that attribute could not be resolved to an underlying type or programming construct, then that element is ignored. Note however that ignored elements might still generate additional parsing errors for additional element requirements that are side effects of that element not being processed. For instance, a particular element content model might require exactly one child element, but if the specified child element was in an `mc:Ignorable` prefix, and the specified child element could not be resolved to a type, then the XAML processor might raise an error.
|
||||
|
||||
`mc:Ignorable` only applies to namespace mappings to identifier strings. `mc:Ignorable` does not apply to namespace mappings into assemblies, which specify a CLR namespace and an assembly (or default to the current executable as the assembly).
|
||||
|
||||
If you are implementing a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor, your processor implementation must not raise parsing or processing errors on type resolution for any element or attribute that is qualified by a prefix that is identified as `mc:Ignorable`. But your processor implementation can still raise exceptions that are a secondary result of an element failing to load or be processed, such as the one-child element example given earlier.
|
||||
If you are implementing a XAML processor, your processor implementation must not raise parsing or processing errors on type resolution for any element or attribute that is qualified by a prefix that is identified as `mc:Ignorable`. But your processor implementation can still raise exceptions that are a secondary result of an element failing to load or be processed, such as the one-child element example given earlier.
|
||||
|
||||
By default, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will ignore content within an ignored element. However, you can specify an additional attribute, [mc:ProcessContent Attribute](mc-processcontent-attribute.md), to require continued processing of content within an ignored element by the next available parent element.
|
||||
By default, a XAML processor will ignore content within an ignored element. However, you can specify an additional attribute, [mc:ProcessContent Attribute](mc-processcontent-attribute.md), to require continued processing of content within an ignored element by the next available parent element.
|
||||
|
||||
Multiple prefixes can be specified in the attribute, using one or more white-space characters as the separator, for example: `mc:Ignorable="ignore1 ignore2"`.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ ms.assetid: 2689b2c8-b4dc-4b71-b9bd-f95e619122d7
|
||||
---
|
||||
# mc:ProcessContent Attribute
|
||||
|
||||
Specifies which [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] elements should still have content processed by relevant parent elements, even if the immediate parent element may be ignored by a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor due to specifying [mc:Ignorable Attribute](mc-ignorable-attribute.md). The `mc:ProcessContent` attribute supports markup compatibility both for custom namespace mapping and for [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] versioning.
|
||||
Specifies which XAML elements should still have content processed by relevant parent elements, even if the immediate parent element may be ignored by a XAML processor due to specifying [mc:Ignorable Attribute](mc-ignorable-attribute.md). The `mc:ProcessContent` attribute supports markup compatibility both for custom namespace mapping and for XAML versioning.
|
||||
|
||||
## XAML Attribute Usage
|
||||
|
||||
@@ -33,12 +33,12 @@ Specifies which [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.
|
||||
|-------|-------------|
|
||||
|*ignorablePrefix*|Any valid prefix string, per the XML 1.0 specification.|
|
||||
|*ignorableUri*|Any valid URI for designating a namespace, per the XML 1.0 specification.|
|
||||
|*ThisElementCanBeIgnored*|An element that can be ignored by [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] processor implementations, if the underlying type cannot be resolved.|
|
||||
|*ThisElementCanBeIgnored*|An element that can be ignored by Extensible Application Markup Language (XAML) processor implementations, if the underlying type cannot be resolved.|
|
||||
|*[content]*|*ThisElementCanBeIgnored* is marked ignorable. If the processor ignores that element, *[content]* is processed by *object*.|
|
||||
|
||||
## Remarks
|
||||
|
||||
By default, a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will ignore content within an ignored element. You can specify a specific element by `mc:ProcessContent`, and a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] processor will continue to process the content within the ignored element. This would typically be used if the content is nested within several tags, at least one of which is ignorable and at least one of which is not ignorable.
|
||||
By default, a XAML processor will ignore content within an ignored element. You can specify a specific element by `mc:ProcessContent`, and a XAML processor will continue to process the content within the ignored element. This would typically be used if the content is nested within several tags, at least one of which is ignorable and at least one of which is not ignorable.
|
||||
|
||||
Multiple prefixes may be specified in the attribute, using a space separator, for example: `mc:ProcessContent="ignore:Element1 ignore:Element2"`.
|
||||
|
||||
|
||||
@@ -7,23 +7,23 @@ helpviewer_keywords:
|
||||
ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc
|
||||
---
|
||||
# Merged Resource Dictionaries
|
||||
[!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] resources support a merged resource dictionary feature. This feature provides a way to define the resources portion of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application outside of the compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] application. Resources can then be shared across applications and are also more conveniently isolated for localization.
|
||||
WPF application outside of the compiled XAML application. Resources can then be shared across applications and are also more conveniently isolated for localization.
|
||||
|
||||
## Introducing a Merged Resource Dictionary
|
||||
In markup, you use the following syntax to introduce a merged resource dictionary into a page:
|
||||
|
||||
[!code-xaml[ResourceMergeDictionary#MergedXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ResourceMergeDictionary/CS/default.xaml#mergedxaml)]
|
||||
|
||||
Note that the <xref:System.Windows.ResourceDictionary> element does not have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive), which is generally required for all items in a resource collection. But another <xref:System.Windows.ResourceDictionary> reference within the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection is a special case, reserved for this merged resource dictionary scenario. The <xref:System.Windows.ResourceDictionary> that introduces a merged resource dictionary cannot have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive). Typically, each <xref:System.Windows.ResourceDictionary> within the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection specifies a <xref:System.Windows.ResourceDictionary.Source%2A> attribute. The value of <xref:System.Windows.ResourceDictionary.Source%2A> should be a uniform resource identifier (URI) that resolves to the location of the resources file to be merged. The destination of that URI must be another [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, with <xref:System.Windows.ResourceDictionary> as its root element.
|
||||
Note that the <xref:System.Windows.ResourceDictionary> element does not have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive), which is generally required for all items in a resource collection. But another <xref:System.Windows.ResourceDictionary> reference within the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection is a special case, reserved for this merged resource dictionary scenario. The <xref:System.Windows.ResourceDictionary> that introduces a merged resource dictionary cannot have an [x:Key Directive](/dotnet/desktop/xaml-services/xkey-directive). Typically, each <xref:System.Windows.ResourceDictionary> within the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection specifies a <xref:System.Windows.ResourceDictionary.Source%2A> attribute. The value of <xref:System.Windows.ResourceDictionary.Source%2A> should be a uniform resource identifier (URI) that resolves to the location of the resources file to be merged. The destination of that URI must be another XAML file, with <xref:System.Windows.ResourceDictionary> as its root element.
|
||||
|
||||
> [!NOTE]
|
||||
> It is legal to define resources within a <xref:System.Windows.ResourceDictionary> that is specified as a merged dictionary, either as an alternative to specifying <xref:System.Windows.ResourceDictionary.Source%2A>, or in addition to whatever resources are included from the specified source. However, this is not a common scenario; the main scenario for merged dictionaries is to merge resources from external file locations. If you want to specify resources within the markup for a page, you should typically define these in the main <xref:System.Windows.ResourceDictionary> and not in the merged dictionaries.
|
||||
|
||||
## Merged Dictionary Behavior
|
||||
Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned will come from the last dictionary found sequentially in the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection. If the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection was defined in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. These scoping rules apply equally for both static resource references and dynamic resource references.
|
||||
Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned will come from the last dictionary found sequentially in the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection. If the <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection was defined in XAML, then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. These scoping rules apply equally for both static resource references and dynamic resource references.
|
||||
|
||||
### Merged Dictionaries and Code
|
||||
Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty <xref:System.Windows.ResourceDictionary> that exists for any `Resources` property also has a default, initially empty <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection property. To add a merged dictionary through code, you obtain a reference to the desired primary <xref:System.Windows.ResourceDictionary>, get its <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> property value, and call `Add` on the generic `Collection` that is contained in <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A>. The object you add must be a new <xref:System.Windows.ResourceDictionary>. In code, you do not set the <xref:System.Windows.ResourceDictionary.Source%2A> property. Instead, you must obtain a <xref:System.Windows.ResourceDictionary> object by either creating one or loading one. One way to load an existing <xref:System.Windows.ResourceDictionary> to call <xref:System.Windows.Markup.XamlReader.Load%2A?displayProperty=nameWithType> on an existing [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file stream that has a <xref:System.Windows.ResourceDictionary> root, then casting the <xref:System.Windows.Markup.XamlReader.Load%2A?displayProperty=nameWithType> return value to <xref:System.Windows.ResourceDictionary>.
|
||||
Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty <xref:System.Windows.ResourceDictionary> that exists for any `Resources` property also has a default, initially empty <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> collection property. To add a merged dictionary through code, you obtain a reference to the desired primary <xref:System.Windows.ResourceDictionary>, get its <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A> property value, and call `Add` on the generic `Collection` that is contained in <xref:System.Windows.ResourceDictionary.MergedDictionaries%2A>. The object you add must be a new <xref:System.Windows.ResourceDictionary>. In code, you do not set the <xref:System.Windows.ResourceDictionary.Source%2A> property. Instead, you must obtain a <xref:System.Windows.ResourceDictionary> object by either creating one or loading one. One way to load an existing <xref:System.Windows.ResourceDictionary> to call <xref:System.Windows.Markup.XamlReader.Load%2A?displayProperty=nameWithType> on an existing XAML file stream that has a <xref:System.Windows.ResourceDictionary> root, then casting the <xref:System.Windows.Markup.XamlReader.Load%2A?displayProperty=nameWithType> return value to <xref:System.Windows.ResourceDictionary>.
|
||||
|
||||
### Merged Resource Dictionary URIs
|
||||
There are several techniques for how to include a merged resource dictionary, which are indicated by the uniform resource identifier (URI) format that you will use. Broadly speaking, these techniques can be divided into two categories: resources that are compiled as part of the project, and resources that are not compiled as part of the project.
|
||||
@@ -31,9 +31,9 @@ ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc
|
||||
For resources that are compiled as part of the project, you can use a relative path that refers to the resource location. The relative path is evaluated during compilation. Your resource must be defined as part of the project as a Resource build action. If you include a resource .xaml file in the project as Resource, you do not need to copy the resource file to the output directory, the resource is already included within the compiled application. You can also use Content build action, but you must then copy the files to the output directory and also deploy the resource files in the same path relationship to the executable.
|
||||
|
||||
> [!NOTE]
|
||||
> Do not use the Embedded Resource build action. The build action itself is supported for [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications, but the resolution of <xref:System.Windows.ResourceDictionary.Source%2A> does not incorporate <xref:System.Resources.ResourceManager>, and thus cannot separate the individual resource out of the stream. You could still use Embedded Resource for other purposes so long as you also used <xref:System.Resources.ResourceManager> to access the resources.
|
||||
> Do not use the Embedded Resource build action. The build action itself is supported for WPF applications, but the resolution of <xref:System.Windows.ResourceDictionary.Source%2A> does not incorporate <xref:System.Resources.ResourceManager>, and thus cannot separate the individual resource out of the stream. You could still use Embedded Resource for other purposes so long as you also used <xref:System.Resources.ResourceManager> to access the resources.
|
||||
|
||||
A related technique is to use a Pack URI to a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, and refer to it as Source. Pack URI enables references to components of referenced assemblies and other techniques. For more information on Pack URIs, see [WPF Application Resource, Content, and Data Files](../app-development/wpf-application-resource-content-and-data-files.md).
|
||||
A related technique is to use a Pack URI to a XAML file, and refer to it as Source. Pack URI enables references to components of referenced assemblies and other techniques. For more information on Pack URIs, see [WPF Application Resource, Content, and Data Files](../app-development/wpf-application-resource-content-and-data-files.md).
|
||||
|
||||
For resources that are not compiled as part of the project, the URI is evaluated at run time. You can use a common URI transport such as file: or http: to refer to the resource file. The disadvantage of using the noncompiled resource approach is that file: access requires additional deployment steps, and http: access implies the Internet security zone.
|
||||
|
||||
@@ -43,7 +43,7 @@ ms.assetid: d159531f-05d4-49fd-b951-c332de51e5bc
|
||||
Writing merged dictionaries as local application files or to local shared storage is another possible merged dictionary / application deployment scenario.
|
||||
|
||||
### Localization
|
||||
If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept as loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], these files can be localized separately. This technique is a lightweight alternative to localizing the satellite resource assemblies. For details, see [WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md).
|
||||
If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept as loose XAML, these files can be localized separately. This technique is a lightweight alternative to localizing the satellite resource assemblies. For details, see [WPF Globalization and Localization Overview](wpf-globalization-and-localization-overview.md).
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ ms.assetid: d655de05-bf63-4814-bc64-6b3be01c70a2
|
||||
---
|
||||
# Migration and Interoperability
|
||||
|
||||
This page contains links to documents that discuss how to implement interoperation between [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] applications and other types of Microsoft Windows applications.
|
||||
This page contains links to documents that discuss how to implement interoperation between Windows Presentation Foundation (WPF) applications and other types of Microsoft Windows applications.
|
||||
|
||||
## In This Section
|
||||
|
||||
@@ -29,10 +29,10 @@ This page contains links to documents that discuss how to implement interoperati
|
||||
|
||||
| Term | Definition |
|
||||
|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| <xref:System.Windows.Forms.Integration.WindowsFormsHost> | An element that you can use to host a Windows Forms control as an element of a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] page. |
|
||||
| <xref:System.Windows.Forms.Integration.ElementHost> | A Windows Forms control that you can use to host a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] control. |
|
||||
| <xref:System.Windows.Interop.HwndSource> | Hosts a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] region within a Win32 application. |
|
||||
| <xref:System.Windows.Interop.HwndHost> | Base class for <xref:System.Windows.Forms.Integration.WindowsFormsHost>, defines some basic functionality that all HWND-based technologies use when hosted by a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. Subclass this to host a Win32 window within a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application. |
|
||||
| <xref:System.Windows.Interop.BrowserInteropHelper> | A helper class for reporting conditions of the browser environment for a [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application that is hosted by a browser. |
|
||||
| <xref:System.Windows.Forms.Integration.WindowsFormsHost> | An element that you can use to host a Windows Forms control as an element of a WPF page. |
|
||||
| <xref:System.Windows.Forms.Integration.ElementHost> | A Windows Forms control that you can use to host a Windows Presentation Foundation (WPF) control. |
|
||||
| <xref:System.Windows.Interop.HwndSource> | Hosts a WPF region within a Win32 application. |
|
||||
| <xref:System.Windows.Interop.HwndHost> | Base class for <xref:System.Windows.Forms.Integration.WindowsFormsHost>, defines some basic functionality that all HWND-based technologies use when hosted by a WPF application. Subclass this to host a Win32 window within a WPF application. |
|
||||
| <xref:System.Windows.Interop.BrowserInteropHelper> | A helper class for reporting conditions of the browser environment for a WPF application that is hosted by a browser. |
|
||||
|
||||
## Related Sections
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user