mirror of
https://github.com/Stone-Red-Code/docs-desktop.git
synced 2026-09-07 07:56:07 +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:
@@ -11,15 +11,15 @@ ms.assetid: cc9cc377-7544-4fd0-b65b-117b90bb0b23
|
||||
---
|
||||
# White-space processing in XAML
|
||||
|
||||
The language rules for XAML state that significant white space must be processed by a [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processor implementation. This article documents these XAML language rules. It also documents additional white-space handling that is defined by the [!INCLUDE[TLA#tla_winclient](../includes/tlasharptla-winclient-md.md)] implementation of the XAML processor and the XAML writer for serialization.
|
||||
The language rules for XAML state that significant white space must be processed by a XAML processor implementation. This article documents these XAML language rules. It also documents additional white-space handling that is defined by the Windows Presentation Foundation (WPF) implementation of the XAML processor and the XAML writer for serialization.
|
||||
|
||||
## White-space definition
|
||||
|
||||
Consistent with XML, white-space characters in [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] are space, linefeed, and tab. These correspond to the Unicode values 0020, 000A, and 0009 respectively.
|
||||
Consistent with XML, white-space characters in XAML are space, linefeed, and tab. These correspond to the Unicode values 0020, 000A, and 0009 respectively.
|
||||
|
||||
## White-space normalization
|
||||
|
||||
By default the following white-space normalization occurs when a [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processor processes a [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] file:
|
||||
By default the following white-space normalization occurs when a XAML processor processes a XAML file:
|
||||
|
||||
1. Linefeed characters between East Asian characters are removed. See the "East Asian Characters" section later in this topic for a definition of this term.
|
||||
|
||||
@@ -47,11 +47,11 @@ The previous normalization rules apply to inner text that is found within XAML
|
||||
|
||||
## Preserving white space
|
||||
|
||||
There are several techniques for preserving white space in the source [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] for eventual presentation that are not affected by [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processor white-space normalization.
|
||||
There are several techniques for preserving white space in the source XAML for eventual presentation that are not affected by XAML processor white-space normalization.
|
||||
|
||||
**xml:space="preserve"**: Specify this attribute at the level of the element where white-space preservation is desired. This preserves all white space, which includes the spaces that might be added by code-editing applications to "pretty-print" align elements as a visually intuitive nesting. However, whether those spaces render is determined by the content model for the containing element. Avoid specifying `xml:space="preserve"` at the root level because most object models do not consider white space as significant regardless of how you set the attribute. Setting `xml:space` globally may have performance consequences on XAML processing (particularly serialization) in some implementations. It is a better practice to only set the attribute specifically at the level of elements that render white space within strings, or are white-space significant collections.
|
||||
|
||||
**Entities and non-breaking spaces**: [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] supports placing any Unicode entity within a text object model. You can use dedicated entities such as nonbreaking space (&\#160; in UTF-8 encoding). You can also use rich text controls that support nonbreaking space characters. You should be cautious if you are using entities to simulate layout characteristics such as indention, because the run-time output of the entities will vary based on a greater number of factors than would the capabilities for producing indention results in a typical layout system, such as proper use of panels and margins. For instance, entities are mapped to fonts and can change size in response to user font selection.
|
||||
**Entities and non-breaking spaces**: XAML supports placing any Unicode entity within a text object model. You can use dedicated entities such as nonbreaking space (&\#160; in UTF-8 encoding). You can also use rich text controls that support nonbreaking space characters. You should be cautious if you are using entities to simulate layout characteristics such as indention, because the run-time output of the entities will vary based on a greater number of factors than would the capabilities for producing indention results in a typical layout system, such as proper use of panels and margins. For instance, entities are mapped to fonts and can change size in response to user font selection.
|
||||
|
||||
## East Asian characters
|
||||
|
||||
@@ -67,9 +67,9 @@ For illustration purposes, the remainder of this section references particular t
|
||||
|
||||
Even for content models that can take strings, the default behavior within these content models is that any white space that remains is not treated as significant. For example, <xref:System.Windows.Controls.ListBox> takes an <xref:System.Collections.IList>, but the white space (such as linefeeds between each <xref:System.Windows.Controls.ListBoxItem>) is not preserved and not rendered. If you attempt to use linefeeds as separators between strings for <xref:System.Windows.Controls.ListBoxItem> items, it does not work at all; the strings that are separated by the linefeeds are treated as one string and one item.
|
||||
|
||||
Those collections that do treat white space as significant are typically part of the flow document model. The primary collection that supports white-space preservation behavior is <xref:System.Windows.Documents.InlineCollection>. This collection class is declared with the <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute>; when this attribute is found, the [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processor will treat white space within the collection as significant. The combination of `xml:space="preserve"` and white space within a <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute> denoted collection is that all white space is preserved and rendered. The combination of `xml:space="default"` and white space within a <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute> causes the initial white-space normalization described earlier, which leaves one space in certain positions, and those spaces are preserved and rendered. Which behavior is desirable is up to you, and you should use `xml:space` selectively to enable the behavior that you want.
|
||||
Those collections that do treat white space as significant are typically part of the flow document model. The primary collection that supports white-space preservation behavior is <xref:System.Windows.Documents.InlineCollection>. This collection class is declared with the <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute>; when this attribute is found, the XAML processor will treat white space within the collection as significant. The combination of `xml:space="preserve"` and white space within a <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute> denoted collection is that all white space is preserved and rendered. The combination of `xml:space="default"` and white space within a <xref:System.Windows.Markup.WhitespaceSignificantCollectionAttribute> causes the initial white-space normalization described earlier, which leaves one space in certain positions, and those spaces are preserved and rendered. Which behavior is desirable is up to you, and you should use `xml:space` selectively to enable the behavior that you want.
|
||||
|
||||
Also, certain inline elements that connote a line break in a flow document model should deliberately not introduce an extra space even in a white-space significant collection. For example, the <xref:System.Windows.Documents.LineBreak> element has the same purpose as the \<BR/> tag in HTML, and for readability in markup, typically a <xref:System.Windows.Documents.LineBreak> is separated from any subsequent text by an authored linefeed. That linefeed should not be normalized to become a leading space in the subsequent line. To enable that behavior, the class definition for the <xref:System.Windows.Documents.LineBreak> element applies the <xref:System.Windows.Markup.TrimSurroundingWhitespaceAttribute>, which is then interpreted by the [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processor to mean that white space surrounding <xref:System.Windows.Documents.LineBreak> is always trimmed.
|
||||
Also, certain inline elements that connote a line break in a flow document model should deliberately not introduce an extra space even in a white-space significant collection. For example, the <xref:System.Windows.Documents.LineBreak> element has the same purpose as the \<BR/> tag in HTML, and for readability in markup, typically a <xref:System.Windows.Documents.LineBreak> is separated from any subsequent text by an authored linefeed. That linefeed should not be normalized to become a leading space in the subsequent line. To enable that behavior, the class definition for the <xref:System.Windows.Documents.LineBreak> element applies the <xref:System.Windows.Markup.TrimSurroundingWhitespaceAttribute>, which is then interpreted by the XAML processor to mean that white space surrounding <xref:System.Windows.Documents.LineBreak> is always trimmed.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ In XAML 2009, `x:Array` is defined as a language primitive instead of a markup e
|
||||
|
||||
## WPF Usage Notes
|
||||
|
||||
Typically, the object elements that populate an `x:Array` are not elements that exist in the [!INCLUDE[TLA2#tla_winclient](../includes/tla2sharptla-winclient-md.md)] XAML namespace, and require a prefix mapping to a non-default XAML namespace.
|
||||
Typically, the object elements that populate an `x:Array` are not elements that exist in the WPF XAML namespace, and require a prefix mapping to a non-default XAML namespace.
|
||||
|
||||
For example, the following is a simple array of two strings, with the `sys` prefix (and also `x`) defined at the level of the array.
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ The `xml:lang` attribute is an XML-defined attribute that declares the language
|
||||
|
||||
## Remarks
|
||||
|
||||
The definition for the `xml:lang` attribute in [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] is derived from `xml:lang` as defined as a "special attribute" by the World Wide Web Consortium (W3C) for XML. Language and culture information is potentially processed in different ways by elements, depending on their implementations; however, there is no default [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processing of the `xml:lang` attribute.
|
||||
The definition for the `xml:lang` attribute in XAML is derived from `xml:lang` as defined as a "special attribute" by the World Wide Web Consortium (W3C) for XML. Language and culture information is potentially processed in different ways by elements, depending on their implementations; however, there is no default XAML processing of the `xml:lang` attribute.
|
||||
|
||||
The default value of the `xml:lang` attribute is an empty string at the attribute level.
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ The value of an `x:Name` directive usage must be unique within a XAML namescope.
|
||||
|
||||
In general, `x:Name` should not be applied in situations that also use `x:Key`. XAML implementations by specific existing frameworks have introduced substitution concepts between `x:Key` and `x:Name`, but that is not a recommended practice. .NET XAML Services does not support such substitution concepts when handling name/key information such as <xref:System.Windows.Markup.INameScope> or <xref:System.Windows.Markup.DictionaryKeyPropertyAttribute>.
|
||||
|
||||
Rules for permittance of `x:Name` as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. However, to be usable with .NET XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of <xref:System.Windows.Markup.INameScope> information in this documentation, and should use the same rules regarding where the information is applied. For example, the [!INCLUDE[TLA#tla_winclient](../includes/tlasharptla-winclient-md.md)] implementation divides various markup elements into separate <xref:System.Windows.NameScope> ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.
|
||||
Rules for permittance of `x:Name` as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. However, to be usable with .NET XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of <xref:System.Windows.Markup.INameScope> information in this documentation, and should use the same rules regarding where the information is applied. For example, the Windows Presentation Foundation (WPF) implementation divides various markup elements into separate <xref:System.Windows.NameScope> ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.
|
||||
|
||||
For custom types that use .NET XAML Services XAML object writers, a property that maps to `x:Name` on a type can be established or changed. You define this behavior by referencing the name of the property to map with the <xref:System.Windows.Markup.RuntimeNamePropertyAttribute> in the type definition code. <xref:System.Windows.Markup.RuntimeNamePropertyAttribute> is a type-level attribute.
|
||||
|
||||
@@ -45,13 +45,13 @@ Using.NET XAML Services, the backing logic for XAML namescope support can be def
|
||||
|
||||
## WPF Usage Notes
|
||||
|
||||
Under the standard build configuration for a [!INCLUDE[TLA2#tla_winclient](../includes/tla2sharptla-winclient-md.md)] application that uses XAML, partial classes, and code-behind, the specified `x:Name` becomes the name of a field that is created in the underlying code when [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] is processed by a markup compilation build task, and that field holds a reference to the object. By default, the created field is internal. You can change field access by specifying the [x:FieldModifier attribute](xfieldmodifier-directive.md). In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Then, a generated method named `InitializeComponent` is called from within the class constructor. `InitializeComponent` consists of `FindName` calls using each of the `x:Name` values that exist in the XAML-defined part of the partial class as input strings. The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. The execution of `InitializeComponent` make it possible to reference the run time object graph using the `x:Name` / field name directly, rather than having to call `FindName` explicitly any time you need a reference to a XAML-defined object.
|
||||
Under the standard build configuration for a WPF application that uses XAML, partial classes, and code-behind, the specified `x:Name` becomes the name of a field that is created in the underlying code when XAML is processed by a markup compilation build task, and that field holds a reference to the object. By default, the created field is internal. You can change field access by specifying the [x:FieldModifier attribute](xfieldmodifier-directive.md). In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. Then, a generated method named `InitializeComponent` is called from within the class constructor. `InitializeComponent` consists of `FindName` calls using each of the `x:Name` values that exist in the XAML-defined part of the partial class as input strings. The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. The execution of `InitializeComponent` make it possible to reference the run time object graph using the `x:Name` / field name directly, rather than having to call `FindName` explicitly any time you need a reference to a XAML-defined object.
|
||||
|
||||
For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with `Page` build action, a separate reference property is created during compilation that adds the `WithEvents` keyword to all elements that have an `x:Name`, to support `Handles` syntax for event handler delegates. This property is always public. For more information, see [Visual Basic and WPF Event Handling](../framework/wpf/advanced/visual-basic-and-wpf-event-handling.md).
|
||||
|
||||
`x:Name` is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). One reason for this behavior is because the `x:Name` is potentially needed for <xref:System.Windows.Data.Binding.ElementName%2A> binding. For details, see [Data Binding Overview](../net/wpf/data/index.md?view=netdesktop-5.0&preserve-view=true).
|
||||
|
||||
As mentioned previously, `x:Name` (or `Name`) should not be applied in situations that also use `x:Key`. The [!INCLUDE[TLA2#tla_winclient](../includes/tla2sharptla-winclient-md.md)] <xref:System.Windows.ResourceDictionary> has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for <xref:System.Windows.Markup.INameScope> APIs as a way to enforce this behavior. If the WPF XAML parser encounters `Name` or `x:Name` in a XAML-defined <xref:System.Windows.ResourceDictionary>, the name is not added to any XAML namescope. Attempting to find that name from any XAML namescope and the `FindName` methods will not return valid results.
|
||||
As mentioned previously, `x:Name` (or `Name`) should not be applied in situations that also use `x:Key`. The WPF <xref:System.Windows.ResourceDictionary> has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for <xref:System.Windows.Markup.INameScope> APIs as a way to enforce this behavior. If the WPF XAML parser encounters `Name` or `x:Name` in a XAML-defined <xref:System.Windows.ResourceDictionary>, the name is not added to any XAML namescope. Attempting to find that name from any XAML namescope and the `FindName` methods will not return valid results.
|
||||
|
||||
### x:Name and Name
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ In WPF, the default `x:Shared` condition for resources is `true`. This condition
|
||||
|
||||
Modifying an object that is returned through a resource API, such as <xref:System.Windows.FrameworkElement.FindResource%2A>, or modifying an object directly within a <xref:System.Windows.ResourceDictionary>, changes the original resource. If references to that resource were dynamic resource references, the consumers of that resource get the changed resource.
|
||||
|
||||
If references to the resource were static resource references, changes to the resource after [!INCLUDE[TLA2#tla_xaml](../includes/tla2sharptla-xaml-md.md)] processing time are irrelevant. For more information about static versus dynamic resource references, see [Overview of XAML resources (WPF .NET)](../net/wpf/systems/xaml-resources-overview.md).
|
||||
If references to the resource were static resource references, changes to the resource after XAML processing time are irrelevant. For more information about static versus dynamic resource references, see [Overview of XAML resources (WPF .NET)](../net/wpf/systems/xaml-resources-overview.md).
|
||||
|
||||
Explicitly specifying `x:Shared="true"` is rarely done, because that is already the default. There is no direct code equivalent for `x:Shared` in the WPF object model; it can only be specified in a XAML usage and must be processed either by the default WPF behavior or in an intermediate XAML node stream on the load path if processed using .NET XAML Services and its XAML readers.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user