Stone_Red/docs-desktop
1
0
Fork 0
mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-08 07:56:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

Replace various WPF include files with content (#1335)

Browse Source 
* net-current-v30plus-md.md

* net-current-v40plus-md.md

* tla2sharptla-ui-md.md

* tla2sharptla-uiautomation-md.md

* tla2sharptla-winclient-md.md

* tla2sharptla-xaml-md.md

* tlasharptla-ui-md.md

* tlasharptla-uiautomation-md.md

* tlasharptla-winclient-md.md

* tlasharptla-xaml-md.md

* fix warnings
This commit is contained in:
Andy (Steve) De George
2022-03-16 12:14:11 -04:00
committed by GitHub
parent dd0052ecec
commit be103da07e
353 changed files with 1339 additions and 1349 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet-desktop-guide/framework/wpf/advanced/xaml-and-custom-classes-for-wpf.md
+9 -9
View File
@@ -8,11 +8,11 @@ helpviewer_keywords:
ms.assetid: e7313137-581e-4a64-8453-d44e15a6164a
---
# XAML and Custom Classes for WPF
XAML as implemented in common language runtime (CLR) frameworks supports the ability to define a custom class or structure in any common language runtime (CLR) language, and then access that class using XAML markup. You can use a mixture of [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)]-defined types and your custom types within the same markup file, typically by mapping the custom types to a XAML namespace prefix. This topic discusses the requirements that a custom class must satisfy to be usable as a XAML element.
XAML as implemented in common language runtime (CLR) frameworks supports the ability to define a custom class or structure in any common language runtime (CLR) language, and then access that class using XAML markup. You can use a mixture of Windows Presentation Foundation (WPF)-defined types and your custom types within the same markup file, typically by mapping the custom types to a XAML namespace prefix. This topic discusses the requirements that a custom class must satisfy to be usable as a XAML element.
<a name="Custom_Classes_in_Applications_vs__in_Assemblies"></a>
## Custom Classes in Applications or Assemblies
Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code that produces the primary [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application, or as a class in a separate assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages and disadvantages.
Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code that produces the primary Windows Presentation Foundation (WPF) application, or as a class in a separate assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages and disadvantages.
- The advantage of creating a class library is that any such custom classes can be shared across many different possible applications. A separate library also makes versioning issues of applications easier to control, and simplifies creating a class where the intended class usage is as a root element on a XAML page.
@@ -26,12 +26,12 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi
- Your custom class must be public and support a default (parameterless) public constructor. (See following section for notes regarding structures.)
- Your custom class must not be a nested class. Nested classes and the "dot" in their general CLR usage syntax interfere with other [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] and/or XAML features such as attached properties.
- Your custom class must not be a nested class. Nested classes and the "dot" in their general CLR usage syntax interfere with other WPF and/or XAML features such as attached properties.
In addition to enabling object element syntax, your object definition also enables property element syntax for any other public properties that take that object as the value type. This is because the object can now be instantiated as an object element and can fill the property element value of such a property.
### Structures
Structures that you define as custom types are always able to be constructed in XAML in [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] .This is because the CLR compilers implicitly create a parameterless constructor for a structure that initializes all property values to their defaults. In some cases, the default construction behavior and/or object element usage for a structure is not desirable. This might be because the structure is intended to fill values and function conceptually as a union, where the values contained might have mutually exclusive interpretations and thus none of its properties are settable. A [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] example of such a structure is <xref:System.Windows.GridLength>. Generally, such structures should implement a type converter such that the values can be expressed in attribute form, using string conventions that create the different interpretations or modes of the structure's values. The structure should also expose similar behavior for code construction through a non-parameterless constructor.
Structures that you define as custom types are always able to be constructed in XAML in WPF .This is because the CLR compilers implicitly create a parameterless constructor for a structure that initializes all property values to their defaults. In some cases, the default construction behavior and/or object element usage for a structure is not desirable. This might be because the structure is intended to fill values and function conceptually as a union, where the values contained might have mutually exclusive interpretations and thus none of its properties are settable. A WPF example of such a structure is <xref:System.Windows.GridLength>. Generally, such structures should implement a type converter such that the values can be expressed in attribute form, using string conventions that create the different interpretations or modes of the structure's values. The structure should also expose similar behavior for code construction through a non-parameterless constructor.
<a name="Requirements_for_Properties_of_a_Custom_Class_as_XAML"></a>
## Requirements for Properties of a Custom Class as XAML Attributes
@@ -51,9 +51,9 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi
Examples of properties where attribute syntax is allowed but property element syntax that contains an object element is disallowed through XAML are various properties that take the <xref:System.Windows.Input.Cursor> type. The <xref:System.Windows.Input.Cursor> class has a dedicated type converter <xref:System.Windows.Input.CursorConverter>, but does not expose a parameterless constructor, so the <xref:System.Windows.FrameworkElement.Cursor%2A> property can only be set through attribute syntax even though the actual <xref:System.Windows.Input.Cursor> type is a reference type.
### Per-Property Type Converters
Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as input for a <xref:System.ComponentModel.TypeConverter.ConvertFrom%2A> operation based on the appropriate type. Typically this is done to provide a convenience accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type converters for attributes where you want to use existing CLR types that do not supply either a parameterless constructor or an attributed type converter. Examples from the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] API are certain properties that take the <xref:System.Globalization.CultureInfo> type. In this case, [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] used the existing Microsoft .NET Framework <xref:System.Globalization.CultureInfo> type to better address compatibility and migration scenarios that were used in earlier versions of frameworks, but the <xref:System.Globalization.CultureInfo> type did not support the necessary constructors or type-level type conversion to be usable as a XAML property value directly.
Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as input for a <xref:System.ComponentModel.TypeConverter.ConvertFrom%2A> operation based on the appropriate type. Typically this is done to provide a convenience accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type converters for attributes where you want to use existing CLR types that do not supply either a parameterless constructor or an attributed type converter. Examples from the WPF API are certain properties that take the <xref:System.Globalization.CultureInfo> type. In this case, WPF used the existing Microsoft .NET Framework <xref:System.Globalization.CultureInfo> type to better address compatibility and migration scenarios that were used in earlier versions of frameworks, but the <xref:System.Globalization.CultureInfo> type did not support the necessary constructors or type-level type conversion to be usable as a XAML property value directly.
Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should strongly consider backing that property with a dependency property. This is particularly true if you use the existing [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] implementation of the XAML processor, because you can improve performance by using <xref:System.Windows.DependencyProperty> backing. A dependency property will expose property system features for your property that users will come to expect for a XAML accessible property. This includes features such as animation, data binding, and style support. For more information, see [Custom Dependency Properties](custom-dependency-properties.md) and [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md).
Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should strongly consider backing that property with a dependency property. This is particularly true if you use the existing Windows Presentation Foundation (WPF) implementation of the XAML processor, because you can improve performance by using <xref:System.Windows.DependencyProperty> backing. A dependency property will expose property system features for your property that users will come to expect for a XAML accessible property. This includes features such as animation, data binding, and style support. For more information, see [Custom Dependency Properties](custom-dependency-properties.md) and [XAML Loading and Dependency Properties](xaml-loading-and-dependency-properties.md).
### Writing and Attributing a Type Converter
You occasionally will need to write a custom <xref:System.ComponentModel.TypeConverter> derived class to provide type conversion for your property type. For instructions on how to derive from and create a type converter that can support XAML usages, and how to apply the <xref:System.ComponentModel.TypeConverterAttribute>, see [TypeConverters and XAML](typeconverters-and-xaml.md).
@@ -81,12 +81,12 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi
- Derives from <xref:System.Array> (for more information about arrays in XAML, see [x:Array Markup Extension](/dotnet/desktop/xaml-services/xarray-markup-extension).)
- Implements <xref:System.Windows.Markup.IAddChild> (an interface defined by [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)]).
- Implements <xref:System.Windows.Markup.IAddChild> (an interface defined by WPF).
Each of these types in CLR has an `Add` method, which is used by the XAML processor to add items to the underlying collection when creating the object graph.
> [!NOTE]
> The generic `List` and `Dictionary` interfaces (<xref:System.Collections.Generic.IList%601> and <xref:System.Collections.Generic.IDictionary%602>) are not supported for collection detection by the [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] XAML processor. However, you can use the <xref:System.Collections.Generic.List%601> class as a base class, because it implements <xref:System.Collections.IList> directly, or <xref:System.Collections.Generic.Dictionary%602> as a base class, because it implements <xref:System.Collections.IDictionary> directly.
> The generic `List` and `Dictionary` interfaces (<xref:System.Collections.Generic.IList%601> and <xref:System.Collections.Generic.IDictionary%602>) are not supported for collection detection by the WPF XAML processor. However, you can use the <xref:System.Collections.Generic.List%601> class as a base class, because it implements <xref:System.Collections.IList> directly, or <xref:System.Collections.Generic.Dictionary%602> as a base class, because it implements <xref:System.Collections.IDictionary> directly.
When you declare a property that takes a collection, be cautious about how that property value is initialized in new instances of the type. If you are not implementing the property as a dependency property, then having the property use a backing field that calls the collection type constructor is adequate. If your property is a dependency property, then you may need to initialize the collection property as part of the default type constructor. This is because a dependency property takes its default value from metadata, and you typically do not want the initial value of a collection property to be a static, shared collection. There should be a collection instance per each containing type instance. For more information, see [Custom Dependency Properties](custom-dependency-properties.md).
@@ -94,7 +94,7 @@ XAML as implemented in common language runtime (CLR) frameworks supports the abi
<a name="XAMLCONtent"></a>
## Declaring XAML Content Properties
The XAML language defines the concept of a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content property. Each class that is usable in object syntax can have exactly one XAML content property. To declare a property to be the XAML content property for your class, apply the <xref:System.Windows.Markup.ContentPropertyAttribute> as part of the class definition. Specify the name of the intended XAML content property as the <xref:System.Windows.Markup.ContentPropertyAttribute.Name%2A> in the attribute. The property is specified as a string by name, not as a reflection construct such as <xref:System.Reflection.PropertyInfo>.
The XAML language defines the concept of a XAML content property. Each class that is usable in object syntax can have exactly one XAML content property. To declare a property to be the XAML content property for your class, apply the <xref:System.Windows.Markup.ContentPropertyAttribute> as part of the class definition. Specify the name of the intended XAML content property as the <xref:System.Windows.Markup.ContentPropertyAttribute.Name%2A> in the attribute. The property is specified as a string by name, not as a reflection construct such as <xref:System.Reflection.PropertyInfo>.
You can specify a collection property to be the XAML content property. This results in a usage for that property whereby the object element can have one or more child elements, without any intervening collection object elements or property element tags. These elements are then treated as the value for the XAML content property and added to the backing collection instance.