More xrefs (#1393)
* Add xrefs. * Fix xref. * Change xref format * Edit. * DataTemplate xrefs. * DataTemplateSelector xrefs. * ControlTemplate xrefs * More xrefs. * More xrefs * XAML Color xrefs. * Fundamentals Color xrefs. * iOS Color xrefs. * Migration Color xrefs. * UI Color xrefs. * DynamicResource xrefs. * Markup extension xrefs * Fix broken xref. * Edits.
This commit is contained in:
David Britch
GitHub
Родитель
d1fd2e905b
Коммит
7c806dbfda
|
|
@ -32,17 +32,17 @@ Semantic properties are used to define information about which controls should r
|
|||
> [!IMPORTANT]
|
||||
> Semantic properties don't try to force equivalent behavior on each platform. Instead, they rely on the accessibility experience provided by each platform.
|
||||
|
||||
The `SemanticProperties` class defines the following attached properties:
|
||||
The <xref:Microsoft.Maui.Controls.SemanticProperties> class defines the following attached properties:
|
||||
|
||||
- `Description`, of type `string`, which represents a description that will be read aloud by the screen reader. For more information, see [Description](#description).
|
||||
- `Hint`, of type `string`, which is similar to `Description`, but provides additional context such as the purpose of a control. For more information, see [Hint](#hint).
|
||||
- `HeadingLevel`, of type `SemanticHeadingLevel`, which enables an element to be marked as a heading to organize the UI and make it easier to navigate. For more information, see [Heading levels](#heading-levels).
|
||||
- [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty), of type `string`, which represents a description that will be read aloud by the screen reader. For more information, see [Description](#description).
|
||||
- [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty), of type `string`, which is similar to `Description`, but provides additional context such as the purpose of a control. For more information, see [Hint](#hint).
|
||||
- [`HeadingLevel`](xref:Microsoft.Maui.Controls.SemanticProperties.HeadingLevelProperty), of type <xref:Microsoft.Maui.SemanticHeadingLevel>, which enables an element to be marked as a heading to organize the UI and make it easier to navigate. For more information, see [Heading levels](#heading-levels).
|
||||
|
||||
These attached properties set platform accessibility values so that a screen reader can speak about the element. For more information about attached properties, see [Attached properties](~/fundamentals/attached-properties.md).
|
||||
|
||||
### Description
|
||||
|
||||
The `SemanticProperties.Description` attached property represents a short, descriptive `string` that a screen reader uses to announce an element. This property should be set for elements that have a meaning that's important for understanding the content or interacting with the user interface. Setting this property can be accomplished in XAML:
|
||||
The [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) attached property represents a short, descriptive `string` that a screen reader uses to announce an element. This property should be set for elements that have a meaning that's important for understanding the content or interacting with the user interface. Setting this property can be accomplished in XAML:
|
||||
|
||||
```xaml
|
||||
<Image Source="dotnet_bot.png"
|
||||
|
|
@ -56,14 +56,14 @@ Image image = new Image { Source = "dotnet_bot.png" };
|
|||
SemanticProperties.SetDescription(image, "Cute dot net bot waving hi to you!");
|
||||
```
|
||||
|
||||
In addition, the `SetValue` method can also be used to set the `SemanticProperties.Description` attached property:
|
||||
In addition, the <xref:Microsoft.Maui.Controls.BindableObject.SetValue%2A> method can also be used to set the [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) attached property:
|
||||
|
||||
```csharp
|
||||
image.SetValue(SemanticProperties.DescriptionProperty, "Cute dot net bot waving hi to you!");
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
> Avoid setting the `SemanticProperties.Description` attached property on a <xref:Microsoft.Maui.Controls.Label>. This will stop the `Text` property being spoken by the screen reader. This is because the visual text should ideally match the text read aloud by the screen reader.
|
||||
> Avoid setting the [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) attached property on a <xref:Microsoft.Maui.Controls.Label>. This will stop the `Text` property being spoken by the screen reader. This is because the visual text should ideally match the text read aloud by the screen reader.
|
||||
|
||||
The accessibility information for an element can also be defined on another element. For example, a <xref:Microsoft.Maui.Controls.Label> next to an <xref:Microsoft.Maui.Controls.Entry> can be used to describe what the <xref:Microsoft.Maui.Controls.Entry> represents. This can be accomplished in XAML as follows:
|
||||
|
||||
|
|
@ -85,11 +85,11 @@ SemanticProperties.SetDescription(entry, label.Text);
|
|||
```
|
||||
|
||||
> [!WARNING]
|
||||
> On iOS, if you set the `SemanticDescription` property on any control that has children the screen reader will be unable to reach the children. This is because iOS doesn't provide accessibility features that allow the navigation from a parent element into a child element.
|
||||
> On iOS, if you set the [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) property on any control that has children the screen reader will be unable to reach the children. This is because iOS doesn't provide accessibility features that allow the navigation from a parent element into a child element.
|
||||
|
||||
### Hint
|
||||
|
||||
The `SemanticProperties.Hint` attached property represents a `string` that provides additional context to the `SemanticProperties.Description` attached property, such as the purpose of a control. Setting this property can be accomplished in XAML:
|
||||
The [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty) attached property represents a `string` that provides additional context to the [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) attached property, such as the purpose of a control. Setting this property can be accomplished in XAML:
|
||||
|
||||
```xaml
|
||||
<Image Source="like.png"
|
||||
|
|
@ -105,7 +105,7 @@ SemanticProperties.SetDescription(image, "Like");
|
|||
SemanticProperties.SetHint(image, "Like this post.");
|
||||
```
|
||||
|
||||
In addition, the `SetValue` method can also be used to set the `SemanticProperties.Hint` attached property:
|
||||
In addition, the <xref:Microsoft.Maui.Controls.BindableObject.SetValue%2A> method can also be used to set the [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty) attached property:
|
||||
|
||||
```csharp
|
||||
image.SetValue(SemanticProperties.HintProperty, "Like this post.");
|
||||
|
|
@ -114,18 +114,18 @@ image.SetValue(SemanticProperties.HintProperty, "Like this post.");
|
|||
On Android, this property behaves slightly differently depending on the control it's attached to. For example, for controls without text values, such as <xref:Microsoft.Maui.Controls.Switch> and <xref:Microsoft.Maui.Controls.CheckBox>, the controls will display the hint with the control. However, for controls with text values, the hint is not displayed and is read after the text value.
|
||||
|
||||
> [!WARNING]
|
||||
> The `SemanticProperties.Hint` property conflicts with the `Entry.Placeholder` property on Android, which both map to the same platform property. Therefore, setting a different `SemanticProperties.Hint` value to the `Entry.Placeholder` value isn't recommended.
|
||||
> The [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty) property conflicts with the `Entry.Placeholder` property on Android, which both map to the same platform property. Therefore, setting a different [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty) value to the `Entry.Placeholder` value isn't recommended.
|
||||
|
||||
<!-- ^ and Editor? -->
|
||||
|
||||
### Heading levels
|
||||
|
||||
The `SemanticProperties.HeadingLevel` attached property enables an element to be marked as a heading to organize the UI and make it easier to navigate. Some screen readers enable users to quickly jump between headings.
|
||||
The [`HeadingLevel`](xref:Microsoft.Maui.Controls.SemanticProperties.HeadingLevelProperty) attached property enables an element to be marked as a heading to organize the UI and make it easier to navigate. Some screen readers enable users to quickly jump between headings.
|
||||
|
||||
Headings have a level from 1 to 9, and are represented by the `SemanticHeadingLevel` enumeration, which defines `None`, and `Level1` through `Level9` members.
|
||||
Headings have a level from 1 to 9, and are represented by the <xref:Microsoft.Maui.SemanticHeadingLevel> enumeration, which defines `None`, and `Level1` through `Level9` members.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> While Windows offers 9 levels of headings, Android and iOS only offer a single heading. Therefore, when `SemanticProperties.HeadingLevel` is set on Windows it maps to the correct heading level. However, when set on Android and iOS it maps to a single heading level.
|
||||
> While Windows offers 9 levels of headings, Android and iOS only offer a single heading. Therefore, when [`HeadingLevel`](xref:Microsoft.Maui.Controls.SemanticProperties.HeadingLevelProperty) is set on Windows it maps to the correct heading level. However, when set on Android and iOS it maps to a single heading level.
|
||||
|
||||
The following example demonstrates setting this attached property:
|
||||
|
||||
|
|
@ -161,7 +161,7 @@ SemanticProperties.SetHeadingLevel(label5, SemanticHeadingLevel.Level1);
|
|||
SemanticProperties.SetHeadingLevel(label7, SemanticHeadingLevel.Level1);
|
||||
```
|
||||
|
||||
In addition, the `SetValue` method can also be used to set the `SemanticProperties.HeadingLevel` attached property:
|
||||
In addition, the <xref:Microsoft.Maui.Controls.BindableObject.SetValue%2A> method can also be used to set the [`HeadingLevel`](xref:Microsoft.Maui.Controls.SemanticProperties.HeadingLevelProperty) attached property:
|
||||
|
||||
```csharp
|
||||
label1.SetValue(SemanticProperties.HeadingLevelProperty, SemanticHeadingLevel.Level1);
|
||||
|
|
@ -169,7 +169,7 @@ label1.SetValue(SemanticProperties.HeadingLevelProperty, SemanticHeadingLevel.Le
|
|||
|
||||
## Semantic focus
|
||||
|
||||
Controls have a `SetSemanticFocus` extension method, defined in the `Microsoft.Maui` namespace, which forces screen reader focus to a specified element. For example, given a <xref:Microsoft.Maui.Controls.Label> named `label`, screen reader focus can be forced to the element with the following code:
|
||||
Controls have a <xref:Microsoft.Maui.SemanticExtensions.SetSemanticFocus%2A> extension method which forces screen reader focus to a specified element. For example, given a <xref:Microsoft.Maui.Controls.Label> named `label`, screen reader focus can be forced to the element with the following code:
|
||||
|
||||
```csharp
|
||||
label.SetSemanticFocus();
|
||||
|
|
@ -177,9 +177,9 @@ label.SetSemanticFocus();
|
|||
|
||||
## Semantic screen reader
|
||||
|
||||
.NET MAUI provides the `ISemanticScreenReader` interface, with which you can instruct a screen reader to announce text to the user. The interface is exposed through the `SemanticScreenReader.Default` property, and is available in the `Microsoft.Maui.Accessibility` namespace.
|
||||
.NET MAUI provides the <xref:Microsoft.Maui.Accessibility.ISemanticScreenReader> interface, with which you can instruct a screen reader to announce text to the user. The interface is exposed through the <xref:Microsoft.Maui.Accessibility.SemanticScreenReader.Default> property, and is available in the <xref:Microsoft.Maui.Accessibility> namespace.
|
||||
|
||||
To instruct a screen reader to announce text, use the `Announce` method, passing a `string` argument that represents the text. The following example demonstrates using this method:
|
||||
To instruct a screen reader to announce text, use the <xref:Microsoft.Maui.Accessibility.SemanticScreenReader.Announce%2A> method, passing a `string` argument that represents the text. The following example demonstrates using this method:
|
||||
|
||||
```csharp
|
||||
SemanticScreenReader.Default.Announce("This is the announcement text.");
|
||||
|
|
@ -199,13 +199,13 @@ Link to semantic effects (.NET MAUI Community Toolkit) which combines `IsInAcces
|
|||
|
||||
Automation properties are attached properties that can be added to any element to indicate how the element is reported to the underlying platform's accessibility framework.
|
||||
|
||||
The `AutomationProperties` class defines the following attached properties:
|
||||
The <xref:Microsoft.Maui.Controls.AutomationProperties> class defines the following attached properties:
|
||||
|
||||
- `ExcludedWithChildren`, of type `bool?`, determines if an element and its children should be excluded from the accessibility tree. For more information, see [ExcludedWithChildren](#excludedwithchildren).
|
||||
- `IsInAccessibleTree`, of type `bool?`, indicates whether the element is available in the accessibility tree. For more information, see [IsInAccessibleTree](#isinaccessibletree).
|
||||
- `Name`, of type `string`, represents a short description of the element that serves as a speakable identifier for that element. For more information, see [Name](#name).
|
||||
- `HelpText`, of type `string`, represents a longer description of the element, which can be thought of as tooltip text that's associated with the element. For more information, see [HelpText](#helptext).
|
||||
- `LabeledBy`, of type <xref:Microsoft.Maui.Controls.VisualElement>, which enables another element to define accessibility information for the current element. For more information, see [LabeledBy](#labeledby).
|
||||
- [`ExcludedWithChildren`](xref:Microsoft.Maui.Controls.AutomationProperties.ExcludedWithChildrenProperty), of type `bool?`, determines if an element and its children should be excluded from the accessibility tree. For more information, see [ExcludedWithChildren](#excludedwithchildren).
|
||||
- [`IsInAccessibleTree`](xref:Microsoft.Maui.Controls.AutomationProperties.IsInAccessibleTreeProperty), of type `bool?`, indicates whether the element is available in the accessibility tree. For more information, see [IsInAccessibleTree](#isinaccessibletree).
|
||||
- [`Name`](xref:Microsoft.Maui.Controls.AutomationProperties.NameProperty), of type `string`, represents a short description of the element that serves as a speakable identifier for that element. For more information, see [Name](#name).
|
||||
- [`HelpText`](xref:Microsoft.Maui.Controls.AutomationProperties.HelpTextProperty), of type `string`, represents a longer description of the element, which can be thought of as tooltip text that's associated with the element. For more information, see [HelpText](#helptext).
|
||||
- [`LabeledBy`](xref:Microsoft.Maui.Controls.AutomationProperties.LabeledByProperty), of type <xref:Microsoft.Maui.Controls.VisualElement>, which enables another element to define accessibility information for the current element. For more information, see [LabeledBy](#labeledby).
|
||||
|
||||
These attached properties set platform accessibility values so that a screen reader can speak about the element. For more information about attached properties, see [Attached properties](~/fundamentals/attached-properties.md).
|
||||
|
||||
|
|
@ -216,7 +216,7 @@ Different screen readers read different accessibility values. Therefore, when us
|
|||
|
||||
### ExcludedWithChildren
|
||||
|
||||
The `AutomationProperties.ExcludeWithChildren` attached property, of type `bool?`, determines if an element and its children should be excluded from the accessibility tree. This enables scenarios such as displaying an <xref:Microsoft.Maui.Controls.AbsoluteLayout> over another layout such as a <xref:Microsoft.Maui.Controls.StackLayout>, with the <xref:Microsoft.Maui.Controls.StackLayout> being excluded from the accessibility tree when it's not visible. It can be used from XAML as follows:
|
||||
The [`ExcludedWithChildren`](xref:Microsoft.Maui.Controls.AutomationProperties.ExcludedWithChildrenProperty) attached property, of type `bool?`, determines if an element and its children should be excluded from the accessibility tree. This enables scenarios such as displaying an <xref:Microsoft.Maui.Controls.AbsoluteLayout> over another layout such as a <xref:Microsoft.Maui.Controls.StackLayout>, with the <xref:Microsoft.Maui.Controls.StackLayout> being excluded from the accessibility tree when it's not visible. It can be used from XAML as follows:
|
||||
|
||||
```xaml
|
||||
<StackLayout AutomationProperties.ExcludedWithChildren="true">
|
||||
|
|
@ -232,14 +232,14 @@ StackLayout stackLayout = new StackLayout();
|
|||
AutomationProperties.SetExcludedWithChildren(stackLayout, true);
|
||||
```
|
||||
|
||||
When this attached property is set, .NET MAUI sets the `AutomationProperties.IsInAccessibleTree` attached property to `false` on the specified element and its children.
|
||||
When this attached property is set, .NET MAUI sets the [`IsInAccessibleTree`](xref:Microsoft.Maui.Controls.AutomationProperties.IsInAccessibleTreeProperty) attached property to `false` on the specified element and its children.
|
||||
|
||||
### IsInAccessibleTree
|
||||
|
||||
> [!WARNING]
|
||||
> This attached property should typically remain unset. The majority of controls should be present in the accessibility tree, and the `AutomationProperties.ExcludedWithChildren` attached property can be set in scenarios where an element and its children need removing from the accessibility tree.
|
||||
|
||||
The `AutomationProperties.IsInAccessibleTree` attached property, of type `bool?`, determines if the element is visible to screen readers. It must be set to `true` to use the other automation properties. This can be accomplished in XAML as follows:
|
||||
The [`IsInAccessibleTree`](xref:Microsoft.Maui.Controls.AutomationProperties.IsInAccessibleTreeProperty) attached property, of type `bool?`, determines if the element is visible to screen readers. It must be set to `true` to use the other automation properties. This can be accomplished in XAML as follows:
|
||||
|
||||
```xaml
|
||||
<Entry AutomationProperties.IsInAccessibleTree="true" />
|
||||
|
|
@ -258,9 +258,9 @@ AutomationProperties.SetIsInAccessibleTree(entry, true);
|
|||
### Name
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `AutomationProperties.Name` attached property has been superseded by the `SemanticProperties.Description` attached property.
|
||||
> The [`Name`](xref:Microsoft.Maui.Controls.AutomationProperties.NameProperty) attached property has been superseded by the [`Description`](xref:Microsoft.Maui.Controls.SemanticProperties.DescriptionProperty) attached property.
|
||||
|
||||
The `AutomationProperties.Name` attached property value should be a short, descriptive text string that a screen reader uses to announce an element. This property should be set for elements that have a meaning that is important for understanding the content or interacting with the user interface. This can be accomplished in XAML as follows:
|
||||
The [`Name`](xref:Microsoft.Maui.Controls.AutomationProperties.NameProperty) attached property value should be a short, descriptive text string that a screen reader uses to announce an element. This property should be set for elements that have a meaning that is important for understanding the content or interacting with the user interface. This can be accomplished in XAML as follows:
|
||||
|
||||
```xaml
|
||||
<ActivityIndicator AutomationProperties.IsInAccessibleTree="true"
|
||||
|
|
@ -278,9 +278,9 @@ AutomationProperties.SetName(activityIndicator, "Progress indicator");
|
|||
### HelpText
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `AutomationProperties.HelpText` attached property has been superseded by the `SemanticProperties.Hint` attached property.
|
||||
> The [`HelpText`](xref:Microsoft.Maui.Controls.AutomationProperties.HelpTextProperty) attached property has been superseded by the [`Hint`](xref:Microsoft.Maui.Controls.SemanticProperties.HintProperty) attached property.
|
||||
|
||||
The `AutomationProperties.HelpText` attached property should be set to text that describes the user interface element, and can be thought of as tooltip text associated with the element. This can be accomplished in XAML as follows:
|
||||
The [`HelpText`](xref:Microsoft.Maui.Controls.AutomationProperties.HelpTextProperty) attached property should be set to text that describes the user interface element, and can be thought of as tooltip text associated with the element. This can be accomplished in XAML as follows:
|
||||
|
||||
```xaml
|
||||
<Button Text="Toggle ActivityIndicator"
|
||||
|
|
@ -301,9 +301,9 @@ On some platforms, for edit controls such as an <xref:Microsoft.Maui.Controls.En
|
|||
### LabeledBy
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `AutomationProperties.LabeledBy` attached property has been superseded by bindings. For more information, see [SemanticProperties: Description](#description).
|
||||
> The [`LabeledBy`](xref:Microsoft.Maui.Controls.AutomationProperties.LabeledByProperty) attached property has been superseded by bindings. For more information, see [SemanticProperties: Description](#description).
|
||||
|
||||
The `AutomationProperties.LabeledBy` attached property allows another element to define accessibility information for the current element. For example, a <xref:Microsoft.Maui.Controls.Label> next to an <xref:Microsoft.Maui.Controls.Entry> can be used to describe what the <xref:Microsoft.Maui.Controls.Entry> represents. This can be accomplished in XAML as follows:
|
||||
The [`LabeledBy`](xref:Microsoft.Maui.Controls.AutomationProperties.LabeledByProperty) attached property allows another element to define accessibility information for the current element. For example, a <xref:Microsoft.Maui.Controls.Label> next to an <xref:Microsoft.Maui.Controls.Entry> can be used to describe what the <xref:Microsoft.Maui.Controls.Entry> represents. This can be accomplished in XAML as follows:
|
||||
|
||||
```xaml
|
||||
<Label x:Name="label" Text="Enter your name: " />
|
||||
|
|
|
|||
|
|
@ -113,7 +113,7 @@ Attached properties can also be added to a control by a style. The following XAM
|
|||
</Style>
|
||||
```
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.Style> can be applied to a <xref:Microsoft.Maui.Controls.Label> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> property to the <xref:Microsoft.Maui.Controls.Style> instance using the `StaticResource` markup extension, as demonstrated in the following code example:
|
||||
The <xref:Microsoft.Maui.Controls.Style> can be applied to a <xref:Microsoft.Maui.Controls.Label> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> property to the <xref:Microsoft.Maui.Controls.Style> instance using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension, as demonstrated in the following code example:
|
||||
|
||||
```xaml
|
||||
<Label Text="Label with shadow" Style="{StaticResource ShadowStyle}" />
|
||||
|
|
|
|||
|
|
@ -286,7 +286,7 @@ The following code example shows an *explicit* style for the `NumericValidationS
|
|||
</Style>
|
||||
```
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.Style> can be applied to an <xref:Microsoft.Maui.Controls.Entry> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> property to the style using the `StaticResource` markup extension:
|
||||
The <xref:Microsoft.Maui.Controls.Style> can be applied to an <xref:Microsoft.Maui.Controls.Entry> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> property to the style using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension:
|
||||
|
||||
```xaml
|
||||
<Entry Placeholder="Enter a System.Double" Style="{StaticResource NumericValidationStyle}">
|
||||
|
|
|
|||
|
|
@ -39,11 +39,11 @@ public class CardView : ContentView
|
|||
|
||||
The `CardView` class, which derives from the <xref:Microsoft.Maui.Controls.ContentView> class, represents a custom control that displays data in a card-like layout. The class contains properties, which are backed by bindable properties, for the data it displays. However, the `CardView` class does not define any UI. Instead, the UI will be defined with a control template. For more information about creating <xref:Microsoft.Maui.Controls.ContentView> derived custom controls, see [ContentView](~/user-interface/controls/contentview.md).
|
||||
|
||||
A control template is created with the `ControlTemplate` type. When you create a `ControlTemplate`, you combine <xref:Microsoft.Maui.Controls.View> objects to build the UI for a custom control, or page. A `ControlTemplate` must have only one <xref:Microsoft.Maui.Controls.View> as its root element. However, the root element usually contains other <xref:Microsoft.Maui.Controls.View> objects. The combination of objects makes up the control's visual structure.
|
||||
A control template is created with the <xref:Microsoft.Maui.Controls.ControlTemplate> type. When you create a <xref:Microsoft.Maui.Controls.ControlTemplate>, you combine <xref:Microsoft.Maui.Controls.View> objects to build the UI for a custom control, or page. A <xref:Microsoft.Maui.Controls.ControlTemplate> must have only one <xref:Microsoft.Maui.Controls.View> as its root element. However, the root element usually contains other <xref:Microsoft.Maui.Controls.View> objects. The combination of objects makes up the control's visual structure.
|
||||
|
||||
While a `ControlTemplate` can be defined inline, the typical approach to declaring a `ControlTemplate` is as a resource in a resource dictionary. Because control templates are resources, they obey the same scoping rules that apply to all resources. For example, if you declare a control template in your app-level resource dictionary, the template can be used anywhere in your app. If you define the template in a page, only that page can use the control template. For more information about resources, see [Resource dictionaries](~/fundamentals/resource-dictionaries.md).
|
||||
While a <xref:Microsoft.Maui.Controls.ControlTemplate> can be defined inline, the typical approach to declaring a <xref:Microsoft.Maui.Controls.ControlTemplate> is as a resource in a resource dictionary. Because control templates are resources, they obey the same scoping rules that apply to all resources. For example, if you declare a control template in your app-level resource dictionary, the template can be used anywhere in your app. If you define the template in a page, only that page can use the control template. For more information about resources, see [Resource dictionaries](~/fundamentals/resource-dictionaries.md).
|
||||
|
||||
The following XAML example shows a `ControlTemplate` for `CardView` objects:
|
||||
The following XAML example shows a <xref:Microsoft.Maui.Controls.ControlTemplate> for `CardView` objects:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -108,13 +108,13 @@ The following XAML example shows a `ControlTemplate` for `CardView` objects:
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
When a `ControlTemplate` is declared as a resource, it must have a key specified with the `x:Key` attribute so that it can be identified in the resource dictionary. In this example, the root element of the `CardViewControlTemplate` is a <xref:Microsoft.Maui.Controls.Frame> object. The <xref:Microsoft.Maui.Controls.Frame> object uses the `RelativeSource` markup extension to set its `BindingContext` to the runtime object instance to which the template will be applied, which is known as the *templated parent*. The <xref:Microsoft.Maui.Controls.Frame> object uses a combination of <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Frame>, <xref:Microsoft.Maui.Controls.Image>, <xref:Microsoft.Maui.Controls.Label>, and <xref:Microsoft.Maui.Controls.BoxView> objects to define the visual structure of a `CardView` object. The binding expressions of these objects resolve against `CardView` properties, due to inheriting the `BindingContext` from the root <xref:Microsoft.Maui.Controls.Frame> element. For more information about the `RelativeSource` markup extension, see [Relative bindings](~/fundamentals/data-binding/relative-bindings.md).
|
||||
When a <xref:Microsoft.Maui.Controls.ControlTemplate> is declared as a resource, it must have a key specified with the `x:Key` attribute so that it can be identified in the resource dictionary. In this example, the root element of the `CardViewControlTemplate` is a <xref:Microsoft.Maui.Controls.Frame> object. The <xref:Microsoft.Maui.Controls.Frame> object uses the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension to set its <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> to the runtime object instance to which the template will be applied, which is known as the *templated parent*. The <xref:Microsoft.Maui.Controls.Frame> object uses a combination of <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Frame>, <xref:Microsoft.Maui.Controls.Image>, <xref:Microsoft.Maui.Controls.Label>, and <xref:Microsoft.Maui.Controls.BoxView> objects to define the visual structure of a `CardView` object. The binding expressions of these objects resolve against `CardView` properties, due to inheriting the <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> from the root <xref:Microsoft.Maui.Controls.Frame> element. For more information about the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension, see [Relative bindings](~/fundamentals/data-binding/relative-bindings.md).
|
||||
|
||||
## Consume a ControlTemplate
|
||||
|
||||
A `ControlTemplate` can be applied to a <xref:Microsoft.Maui.Controls.ContentView> derived custom control by setting its `ControlTemplate` property to the control template object. Similarly, a `ControlTemplate` can be applied to a <xref:Microsoft.Maui.Controls.ContentPage> derived page by setting its `ControlTemplate` property to the control template object. At runtime, when a `ControlTemplate` is applied, all of the controls that are defined in the `ControlTemplate` are added to the visual tree of the templated custom control, or templated page.
|
||||
A <xref:Microsoft.Maui.Controls.ControlTemplate> can be applied to a <xref:Microsoft.Maui.Controls.ContentView> derived custom control by setting its <xref:Microsoft.Maui.Controls.ControlTemplate> property to the control template object. Similarly, a <xref:Microsoft.Maui.Controls.ControlTemplate> can be applied to a <xref:Microsoft.Maui.Controls.ContentPage> derived page by setting its <xref:Microsoft.Maui.Controls.ControlTemplate> property to the control template object. At runtime, when a <xref:Microsoft.Maui.Controls.ControlTemplate> is applied, all of the controls that are defined in the <xref:Microsoft.Maui.Controls.ControlTemplate> are added to the visual tree of the templated custom control, or templated page.
|
||||
|
||||
The following example shows the `CardViewControlTemplate` being assigned to the `ControlTemplate` property of each `CardView` object:
|
||||
The following example shows the `CardViewControlTemplate` being assigned to the <xref:Microsoft.Maui.Controls.ControlTemplate> property of each `CardView` object:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -138,36 +138,36 @@ The following example shows the `CardViewControlTemplate` being assigned to the
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the controls in the `CardViewControlTemplate` become part of the visual tree for each `CardView` object. Because the root <xref:Microsoft.Maui.Controls.Frame> object for the control template sets its `BindingContext` to the templated parent, the <xref:Microsoft.Maui.Controls.Frame> and its children resolve their binding expressions against the properties of each `CardView` object.
|
||||
In this example, the controls in the `CardViewControlTemplate` become part of the visual tree for each `CardView` object. Because the root <xref:Microsoft.Maui.Controls.Frame> object for the control template sets its <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> to the templated parent, the <xref:Microsoft.Maui.Controls.Frame> and its children resolve their binding expressions against the properties of each `CardView` object.
|
||||
|
||||
The following screenshot shows the `CardViewControlTemplate` applied to the three `CardView` objects:
|
||||
|
||||
:::image type="content" source="media/controltemplate/relativesource-controltemplate.png" alt-text="Screenshot of two templated CardView objects.":::
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The point in time that a `ControlTemplate` is applied to a control instance can be detected by overriding the `OnApplyTemplate` method in the templated custom control, or templated page. For more information, see [Get a named element from a template](#get-a-named-element-from-a-template).
|
||||
> The point in time that a <xref:Microsoft.Maui.Controls.ControlTemplate> is applied to a control instance can be detected by overriding the <xref:Microsoft.Maui.Controls.TemplatedView.OnApplyTemplate%2A> method in the templated custom control, or templated page. For more information, see [Get a named element from a template](#get-a-named-element-from-a-template).
|
||||
|
||||
## Pass parameters with TemplateBinding
|
||||
|
||||
The `TemplateBinding` markup extension binds a property of an element that is in a `ControlTemplate` to a public property that is defined by the templated custom control or templated page. When you use a `TemplateBinding`, you enable properties on the control to act as parameters to the template. Therefore, when a property on a templated custom control or templated page is set, that value is passed onto the element that has the `TemplateBinding` on it.
|
||||
The [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension binds a property of an element that is in a <xref:Microsoft.Maui.Controls.ControlTemplate> to a public property that is defined by the templated custom control or templated page. When you use a [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension), you enable properties on the control to act as parameters to the template. Therefore, when a property on a templated custom control or templated page is set, that value is passed onto the element that has the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) on it.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `TemplateBinding` markup expression enables the `RelativeSource` binding from the previous control template to be removed, and replaces the `Binding` expressions.
|
||||
> The [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup expression enables the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) binding from the previous control template to be removed, and replaces the `Binding` expressions.
|
||||
|
||||
The `TemplateBinding` markup extension defines the following properties:
|
||||
The [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension defines the following properties:
|
||||
|
||||
- `Path`, of type `string`, the path to the property.
|
||||
- `Mode`, of type `BindingMode`, the direction in which changes propagate between the *source* and *target*.
|
||||
- `Converter`, of type `IValueConverter`, the binding value converter.
|
||||
- `ConverterParameter`, of type `object`, the parameter to the binding value converter.
|
||||
- `StringFormat`, of type `string`, the string format for the binding.
|
||||
- <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.Path>, of type `string`, the path to the property.
|
||||
- <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.Mode>, of type <xref:Microsoft.Maui.Controls.BindingMode>, the direction in which changes propagate between the *source* and *target*.
|
||||
- <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.Converter>, of type <xref:Microsoft.Maui.Controls.IValueConverter>, the binding value converter.
|
||||
- <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.ConverterParameter>, of type `object`, the parameter to the binding value converter.
|
||||
- <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.StringFormat>, of type `string`, the string format for the binding.
|
||||
|
||||
The `ContentProperty` for the `TemplateBinding` markup extension is `Path`. Therefore, the "Path=" part of the markup extension can be omitted if the path is the first item in the `TemplateBinding` expression. For more information about using these properties in a binding expression, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
The `ContentProperty` for the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension is <xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension.Path>. Therefore, the "Path=" part of the markup extension can be omitted if the path is the first item in the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) expression. For more information about using these properties in a binding expression, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
|
||||
> [!WARNING]
|
||||
> The `TemplateBinding` markup extension should only be used within a `ControlTemplate`. However, attempting to use a `TemplateBinding` expression outside of a `ControlTemplate` will not result in a build error or an exception being thrown.
|
||||
> The [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension should only be used within a <xref:Microsoft.Maui.Controls.ControlTemplate>. However, attempting to use a [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) expression outside of a <xref:Microsoft.Maui.Controls.ControlTemplate> will not result in a build error or an exception being thrown.
|
||||
|
||||
The following XAML example shows a `ControlTemplate` for `CardView` objects, that uses the `TemplateBinding` markup extension:
|
||||
The following XAML example shows a <xref:Microsoft.Maui.Controls.ControlTemplate> for `CardView` objects, that uses the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -231,16 +231,16 @@ The following XAML example shows a `ControlTemplate` for `CardView` objects, tha
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `TemplateBinding` markup extension resolves binding expressions against the properties of each `CardView` object. The following screenshot shows the `CardViewControlTemplate` applied to the `CardView` objects:
|
||||
In this example, the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension resolves binding expressions against the properties of each `CardView` object. The following screenshot shows the `CardViewControlTemplate` applied to the `CardView` objects:
|
||||
|
||||
:::image type="content" source="media/controltemplate/templatebinding-controltemplate.png" alt-text="Screenshot of templated CardView objects.":::
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Using the `TemplateBinding` markup extension is equivalent to setting the `BindingContext` of the root element in the template to its templated parent with the `RelativeSource` markup extension, and then resolving bindings of child objects with the `Binding` markup extension. In fact, the `TemplateBinding` markup extension creates a `Binding` whose `Source` is `RelativeBindingSource.TemplatedParent`.
|
||||
> Using the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension is equivalent to setting the <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> of the root element in the template to its templated parent with the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension, and then resolving bindings of child objects with the `Binding` markup extension. In fact, the [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) markup extension creates a `Binding` whose `Source` is `RelativeBindingSource.TemplatedParent`.
|
||||
|
||||
## Apply a ControlTemplate with a style
|
||||
|
||||
Control templates can also be applied with styles. This is achieved by creating an *implicit* or *explicit* style that consumes the `ControlTemplate`.
|
||||
Control templates can also be applied with styles. This is achieved by creating an *implicit* or *explicit* style that consumes the <xref:Microsoft.Maui.Controls.ControlTemplate>.
|
||||
|
||||
The following XAML example shows an *implicit* style that consumes the `CardViewControlTemplate`:
|
||||
|
||||
|
|
@ -274,13 +274,13 @@ The following XAML example shows an *implicit* style that consumes the `CardView
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the *implicit* <xref:Microsoft.Maui.Controls.Style> is automatically applied to each `CardView` object, and sets the `ControlTemplate` property of each `CardView` to `CardViewControlTemplate`.
|
||||
In this example, the *implicit* <xref:Microsoft.Maui.Controls.Style> is automatically applied to each `CardView` object, and sets the <xref:Microsoft.Maui.Controls.ControlTemplate> property of each `CardView` to `CardViewControlTemplate`.
|
||||
|
||||
For more information about styles, see [Styles](~/user-interface/styles/xaml.md).
|
||||
|
||||
## Redefine a control’s UI
|
||||
|
||||
When a `ControlTemplate` is instantiated and assigned to the `ControlTemplate` property of a <xref:Microsoft.Maui.Controls.ContentView> derived custom control, or a <xref:Microsoft.Maui.Controls.ContentPage> derived page, the visual structure defined for the custom control or page is replaced with the visual structure defined in the `ControlTemplate`.
|
||||
When a <xref:Microsoft.Maui.Controls.ControlTemplate> is instantiated and assigned to the <xref:Microsoft.Maui.Controls.ControlTemplate> property of a <xref:Microsoft.Maui.Controls.ContentView> derived custom control, or a <xref:Microsoft.Maui.Controls.ContentPage> derived page, the visual structure defined for the custom control or page is replaced with the visual structure defined in the <xref:Microsoft.Maui.Controls.ControlTemplate>.
|
||||
|
||||
For example, the `CardViewUI` custom control defines its user interface using the following XAML:
|
||||
|
||||
|
|
@ -343,7 +343,7 @@ For example, the `CardViewUI` custom control defines its user interface using th
|
|||
</ContentView>
|
||||
```
|
||||
|
||||
However, the controls that comprise this UI can be replaced by defining a new visual structure in a `ControlTemplate`, and assigning it to the `ControlTemplate` property of a `CardViewUI` object:
|
||||
However, the controls that comprise this UI can be replaced by defining a new visual structure in a <xref:Microsoft.Maui.Controls.ControlTemplate>, and assigning it to the <xref:Microsoft.Maui.Controls.ControlTemplate> property of a `CardViewUI` object:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -391,17 +391,17 @@ However, the controls that comprise this UI can be replaced by defining a new vi
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the visual structure of the `CardViewUI` object is redefined in a `ControlTemplate` that provides a more compact visual structure that's suitable for a condensed list:
|
||||
In this example, the visual structure of the `CardViewUI` object is redefined in a <xref:Microsoft.Maui.Controls.ControlTemplate> that provides a more compact visual structure that's suitable for a condensed list:
|
||||
|
||||
:::image type="content" source="media/controltemplate/redefine-controltemplate.png" alt-text="Screenshot of templated CardViewUI objects.":::
|
||||
|
||||
## Substitute content into a ContentPresenter
|
||||
|
||||
A `ContentPresenter` can be placed in a control template to mark where content to be displayed by the templated custom control or templated page will appear. The custom control or page that consumes the control template will then define content to be displayed by the `ContentPresenter`. The following diagram illustrates a `ControlTemplate` for a page that contains a number of controls, including a `ContentPresenter` marked by a blue rectangle:
|
||||
A <xref:Microsoft.Maui.Controls.ContentPresenter> can be placed in a control template to mark where content to be displayed by the templated custom control or templated page will appear. The custom control or page that consumes the control template will then define content to be displayed by the <xref:Microsoft.Maui.Controls.ContentPresenter>. The following diagram illustrates a <xref:Microsoft.Maui.Controls.ControlTemplate> for a page that contains a number of controls, including a <xref:Microsoft.Maui.Controls.ContentPresenter> marked by a blue rectangle:
|
||||
|
||||
:::image type="content" source="media/controltemplate/controltemplate.png" alt-text="Control template for a ContentPage." border="false":::
|
||||
|
||||
The following XAML shows a control template named `TealTemplate` that contains a `ContentPresenter` in its visual structure:
|
||||
The following XAML shows a control template named `TealTemplate` that contains a <xref:Microsoft.Maui.Controls.ContentPresenter> in its visual structure:
|
||||
|
||||
```xaml
|
||||
<ControlTemplate x:Key="TealTemplate">
|
||||
|
|
@ -442,7 +442,7 @@ The following XAML shows a control template named `TealTemplate` that contains a
|
|||
</ControlTemplate>
|
||||
```
|
||||
|
||||
The following example shows `TealTemplate` assigned to the `ControlTemplate` property of a <xref:Microsoft.Maui.Controls.ContentPage> derived page:
|
||||
The following example shows `TealTemplate` assigned to the <xref:Microsoft.Maui.Controls.ControlTemplate> property of a <xref:Microsoft.Maui.Controls.ContentPage> derived page:
|
||||
|
||||
```xaml
|
||||
<controls:HeaderFooterPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -460,18 +460,18 @@ The following example shows `TealTemplate` assigned to the `ControlTemplate` pro
|
|||
</controls:HeaderFooterPage>
|
||||
```
|
||||
|
||||
At runtime, when `TealTemplate` is applied to the page, the page content is substituted into the `ContentPresenter` defined in the control template:
|
||||
At runtime, when `TealTemplate` is applied to the page, the page content is substituted into the <xref:Microsoft.Maui.Controls.ContentPresenter> defined in the control template:
|
||||
|
||||
:::image type="content" source="media/controltemplate/tealtemplate-contentpage.png" alt-text="Screenshot of templated page object.":::
|
||||
|
||||
## Get a named element from a template
|
||||
|
||||
Named elements within a control template can be retrieved from the templated custom control or templated page. This can be achieved with the `GetTemplateChild` method, which returns the named element in the instantiated `ControlTemplate` visual tree, if found. Otherwise, it returns `null`.
|
||||
Named elements within a control template can be retrieved from the templated custom control or templated page. This can be achieved with the <xref:Microsoft.Maui.Controls.TemplatedView.GetTemplateChild%2A> method, which returns the named element in the instantiated <xref:Microsoft.Maui.Controls.ControlTemplate> visual tree, if found. Otherwise, it returns `null`.
|
||||
|
||||
After a control template has been instantiated, the template's `OnApplyTemplate` method is called. The `GetTemplateChild` method should therefore be called from a `OnApplyTemplate` override in the templated control or templated page.
|
||||
After a control template has been instantiated, the template's <xref:Microsoft.Maui.Controls.TemplatedView.OnApplyTemplate%2A> method is called. The <xref:Microsoft.Maui.Controls.TemplatedView.GetTemplateChild%2A> method should therefore be called from a <xref:Microsoft.Maui.Controls.TemplatedView.OnApplyTemplate%2A> override in the templated control or templated page.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `GetTemplateChild` method should only be called after the `OnApplyTemplate` method has been called.
|
||||
> The <xref:Microsoft.Maui.Controls.TemplatedView.GetTemplateChild%2A> method should only be called after the <xref:Microsoft.Maui.Controls.TemplatedView.OnApplyTemplate%2A> method has been called.
|
||||
|
||||
The following XAML shows a control template named `TealTemplate` that can be applied to <xref:Microsoft.Maui.Controls.ContentPage> derived pages:
|
||||
|
||||
|
|
@ -495,7 +495,7 @@ The following XAML shows a control template named `TealTemplate` that can be app
|
|||
</ControlTemplate>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Label> element is named, and can be retrieved in the code for the templated page. This is achieved by calling the `GetTemplateChild` method from the `OnApplyTemplate` override for the templated page:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Label> element is named, and can be retrieved in the code for the templated page. This is achieved by calling the <xref:Microsoft.Maui.Controls.TemplatedView.GetTemplateChild%2A> method from the <xref:Microsoft.Maui.Controls.TemplatedView.OnApplyTemplate%2A> override for the templated page:
|
||||
|
||||
```csharp
|
||||
public partial class AccessTemplateElementPage : HeaderFooterPage
|
||||
|
|
@ -516,13 +516,13 @@ public partial class AccessTemplateElementPage : HeaderFooterPage
|
|||
}
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Label> object named `changeThemeLabel` is retrieved once the `ControlTemplate` has been instantiated. `changeThemeLabel` can then be accessed and manipulated by the `AccessTemplateElementPage` class. The following screenshot shows that the text displayed by the <xref:Microsoft.Maui.Controls.Label> has been changed:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Label> object named `changeThemeLabel` is retrieved once the <xref:Microsoft.Maui.Controls.ControlTemplate> has been instantiated. `changeThemeLabel` can then be accessed and manipulated by the `AccessTemplateElementPage` class. The following screenshot shows that the text displayed by the <xref:Microsoft.Maui.Controls.Label> has been changed:
|
||||
|
||||
:::image type="content" source="media/controltemplate/get-named-element.png" alt-text="Screenshot of templated page object that's changed.":::
|
||||
|
||||
## Bind to a viewmodel
|
||||
|
||||
A `ControlTemplate` can data bind to a viewmodel, even when the `ControlTemplate` binds to the templated parent (the runtime object instance to which the template is applied).
|
||||
A <xref:Microsoft.Maui.Controls.ControlTemplate> can data bind to a viewmodel, even when the <xref:Microsoft.Maui.Controls.ControlTemplate> binds to the templated parent (the runtime object instance to which the template is applied).
|
||||
|
||||
The following XAML example shows a page that consumes a viewmodel named `PeopleViewModel`:
|
||||
|
||||
|
|
@ -551,7 +551,7 @@ The following XAML example shows a page that consumes a viewmodel named `PeopleV
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `BindingContext` of the page is set to a `PeopleViewModel` instance. This viewmodel exposes a `People` collection and an `ICommand` named `DeletePersonCommand`. The <xref:Microsoft.Maui.Controls.StackLayout> on the page uses a bindable layout to data bind to the `People` collection, and the `ItemTemplate` of the bindable layout is set to the `PersonTemplate` resource. This `DataTemplate` specifies that each item in the `People` collection will be displayed using a `CardView` object. The visual structure of the `CardView` object is defined using a `ControlTemplate` named `CardViewControlTemplate`:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> of the page is set to a `PeopleViewModel` instance. This viewmodel exposes a `People` collection and an `ICommand` named `DeletePersonCommand`. The <xref:Microsoft.Maui.Controls.StackLayout> on the page uses a bindable layout to data bind to the `People` collection, and the [`ItemTemplate`](xref:Microsoft.Maui.Controls.BindableLayout.ItemTemplateProperty) of the bindable layout is set to the `PersonTemplate` resource. This <xref:Microsoft.Maui.Controls.DataTemplate> specifies that each item in the `People` collection will be displayed using a `CardView` object. The visual structure of the `CardView` object is defined using a <xref:Microsoft.Maui.Controls.ControlTemplate> named `CardViewControlTemplate`:
|
||||
|
||||
```xaml
|
||||
<ControlTemplate x:Key="CardViewControlTemplate">
|
||||
|
|
@ -592,11 +592,11 @@ In this example, the `BindingContext` of the page is set to a `PeopleViewModel`
|
|||
</ControlTemplate>
|
||||
```
|
||||
|
||||
In this example, the root element of the `ControlTemplate` is a <xref:Microsoft.Maui.Controls.Frame> object. The <xref:Microsoft.Maui.Controls.Frame> object uses the `RelativeSource` markup extension to set its `BindingContext` to the templated parent. The binding expressions of the <xref:Microsoft.Maui.Controls.Frame> object and its children resolve against `CardView` properties, due to inheriting the `BindingContext` from the root <xref:Microsoft.Maui.Controls.Frame> element. The following screenshot shows the page displaying the `People` collection:
|
||||
In this example, the root element of the <xref:Microsoft.Maui.Controls.ControlTemplate> is a <xref:Microsoft.Maui.Controls.Frame> object. The <xref:Microsoft.Maui.Controls.Frame> object uses the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension to set its <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> to the templated parent. The binding expressions of the <xref:Microsoft.Maui.Controls.Frame> object and its children resolve against `CardView` properties, due to inheriting the <xref:Microsoft.Maui.Controls.BindableObject.BindingContext> from the root <xref:Microsoft.Maui.Controls.Frame> element. The following screenshot shows the page displaying the `People` collection:
|
||||
|
||||
:::image type="content" source="media/controltemplate/viewmodel-controltemplate.png" alt-text="Screenshot of three templated CardView objects that bind to a viewmodel.":::
|
||||
|
||||
While the objects in the `ControlTemplate` bind to properties on its templated parent, the <xref:Microsoft.Maui.Controls.Button> within the control template binds to both its templated parent, and to the `DeletePersonCommand` in the viewmodel. This is because the `Button.Command` property redefines its binding source to be the binding context of the ancestor whose binding context type is `PeopleViewModel`, which is the <xref:Microsoft.Maui.Controls.StackLayout>. The `Path` part of the binding expressions can then resolve the `DeletePersonCommand` property. However, the `Button.CommandParameter` property doesn't alter its binding source, instead inheriting it from its parent in the `ControlTemplate`. Therefore, the `CommandParameter` property binds to the `CardTitle` property of the `CardView`.
|
||||
While the objects in the <xref:Microsoft.Maui.Controls.ControlTemplate> bind to properties on its templated parent, the <xref:Microsoft.Maui.Controls.Button> within the control template binds to both its templated parent, and to the `DeletePersonCommand` in the viewmodel. This is because the `Button.Command` property redefines its binding source to be the binding context of the ancestor whose binding context type is `PeopleViewModel`, which is the <xref:Microsoft.Maui.Controls.StackLayout>. The `Path` part of the binding expressions can then resolve the `DeletePersonCommand` property. However, the `Button.CommandParameter` property doesn't alter its binding source, instead inheriting it from its parent in the <xref:Microsoft.Maui.Controls.ControlTemplate>. Therefore, the `CommandParameter` property binds to the `CardTitle` property of the `CardView`.
|
||||
|
||||
The overall effect of the <xref:Microsoft.Maui.Controls.Button> bindings is that when the <xref:Microsoft.Maui.Controls.Button> is tapped, the `DeletePersonCommand` in the `PeopleViewModel` class is executed, with the value of the `CardName` property being passed to the `DeletePersonCommand`. This results in the specified `CardView` being removed from the bindable layout.
|
||||
|
||||
|
|
|
|||
|
|
@ -228,7 +228,7 @@ In this example, the `Source` and `Path` properties are regular XAML attributes.
|
|||
|
||||
This syntax isn't common, but sometimes it's necessary when complex objects are involved.
|
||||
|
||||
The examples shown so far set the `BindingContext` property and the `Source` property of `Binding` to an `x:Reference` markup extension to reference another view on the page. These two properties are of type `Object`, and they can be set to any object that includes properties that are suitable for binding sources. You can also set the `BindingContext` or `Source` property to an `x:Static` markup extension to reference the value of a static property or field, or a `StaticResource` markup extension to reference an object stored in a resource dictionary, or directly to an object, which is often an instance of a viewmodel.
|
||||
The examples shown so far set the `BindingContext` property and the `Source` property of `Binding` to an `x:Reference` markup extension to reference another view on the page. These two properties are of type `Object`, and they can be set to any object that includes properties that are suitable for binding sources. You can also set the `BindingContext` or `Source` property to an `x:Static` markup extension to reference the value of a static property or field, or a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension to reference an object stored in a resource dictionary, or directly to an object, which is often an instance of a viewmodel.
|
||||
|
||||
> [!NOTE]
|
||||
> The `BindingContext` property can also be set to a `Binding` object so that the `Source` and `Path` properties of `Binding` define the binding context.
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ The following example demonstrates setting the `FallbackValue` property:
|
|||
|
||||
The binding on the <xref:Microsoft.Maui.Controls.Label> defines a `FallbackValue` value (delimited by single-quote characters) that will be set on the target if the binding source can't be resolved. Therefore, the value defined by the `FallbackValue` property will be displayed if the `Population` property doesn't exist on the bound object.
|
||||
|
||||
Rather than defining `FallbackValue` property values inline, it's recommended to define them as resources in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The advantage of this approach is that such values are defined once in a single location, and are more easily localizable. The resources can then be retrieved using the `StaticResource` markup extension:
|
||||
Rather than defining `FallbackValue` property values inline, it's recommended to define them as resources in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The advantage of this approach is that such values are defined once in a single location, and are more easily localizable. The resources can then be retrieved using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension:
|
||||
|
||||
```xaml
|
||||
<Label Text="{Binding Population, FallbackValue={StaticResource populationUnknown}}"
|
||||
|
|
@ -73,7 +73,7 @@ The following example demonstrates setting the `TargetNullValue` property:
|
|||
|
||||
The bindings on the <xref:Microsoft.Maui.Controls.Image> and <xref:Microsoft.Maui.Controls.Label> both define `TargetNullValue` values (delimited by single-quote characters) that will be applied if the binding path returns `null`. Therefore, the values defined by the `TargetNullValue` properties will be displayed for any objects in the collection where the `ImageUrl` and `Location` properties are not defined.
|
||||
|
||||
Rather than defining `TargetNullValue` property values inline, it's recommended to define them as resources in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The advantage of this approach is that such values are defined once in a single location, and are more easily localizable. The resources can then be retrieved using the `StaticResource` markup extension:
|
||||
Rather than defining `TargetNullValue` property values inline, it's recommended to define them as resources in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The advantage of this approach is that such values are defined once in a single location, and are more easily localizable. The resources can then be retrieved using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension:
|
||||
|
||||
```xaml
|
||||
<Image Source="{Binding ImageUrl, TargetNullValue={StaticResource fallbackImageUrl}}"
|
||||
|
|
|
|||
|
|
@ -76,9 +76,9 @@ For more information about this color selector, see [ViewModels and property-cha
|
|||
|
||||
## Use compiled bindings in a DataTemplate
|
||||
|
||||
Bindings in a `DataTemplate` are interpreted in the context of the object being templated. Therefore, when using compiled bindings in a `DataTemplate`, the `DataTemplate` needs to declare the type of its data object using the `x:DataType` attribute.
|
||||
Bindings in a <xref:Microsoft.Maui.Controls.DataTemplate> are interpreted in the context of the object being templated. Therefore, when using compiled bindings in a <xref:Microsoft.Maui.Controls.DataTemplate>, the <xref:Microsoft.Maui.Controls.DataTemplate> needs to declare the type of its data object using the `x:DataType` attribute.
|
||||
|
||||
The following example demonstrates using compiled bindings in a `DataTemplate`:
|
||||
The following example demonstrates using compiled bindings in a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -113,7 +113,7 @@ The following example demonstrates using compiled bindings in a `DataTemplate`:
|
|||
|
||||
The `ListView.ItemsSource` property is set to the static `NamedColor.All` property. The `NamedColor` class uses .NET reflection to enumerate all the static public fields in the <xref:Microsoft.Maui.Graphics.Colors> class, and to store them with their names in a collection that is accessible from the static `All` property. Therefore, the <xref:Microsoft.Maui.Controls.ListView> is filled with all of the `NamedColor` instances. For each item in the <xref:Microsoft.Maui.Controls.ListView>, the binding context for the item is set to a `NamedColor` object. The <xref:Microsoft.Maui.Controls.BoxView> and <xref:Microsoft.Maui.Controls.Label> elements in the <xref:Microsoft.Maui.Controls.ViewCell> are bound to `NamedColor` properties.
|
||||
|
||||
The `DataTemplate` defines the `x:DataType` attribute to be the `NamedColor` type, indicating that any binding expressions in the `DataTemplate` view hierarchy will be compiled. This can be verified by changing any of the binding expressions to bind to a non-existent `NamedColor` property, which will result in a build error. While this example sets the `x:DataType` attribute to a string literal, it can also be set to a type with the `x:Type` markup extension. For more information about the `x:Type` markup extension, see [x:Type Markup Extension](~/xaml/markup-extensions/consume.md#xtype-markup-extension).
|
||||
The <xref:Microsoft.Maui.Controls.DataTemplate> defines the `x:DataType` attribute to be the `NamedColor` type, indicating that any binding expressions in the <xref:Microsoft.Maui.Controls.DataTemplate> view hierarchy will be compiled. This can be verified by changing any of the binding expressions to bind to a non-existent `NamedColor` property, which will result in a build error. While this example sets the `x:DataType` attribute to a string literal, it can also be set to a type with the `x:Type` markup extension. For more information about the `x:Type` markup extension, see [x:Type Markup Extension](~/xaml/markup-extensions/consume.md#xtype-markup-extension).
|
||||
|
||||
When the example is first run, the <xref:Microsoft.Maui.Controls.ListView> is populated with `NamedColor` instances. When an item in the <xref:Microsoft.Maui.Controls.ListView> is selected, the `BoxView.Color` property is set to the color of the selected item in the <xref:Microsoft.Maui.Controls.ListView>:
|
||||
|
||||
|
|
@ -123,7 +123,7 @@ Selecting other items in the <xref:Microsoft.Maui.Controls.ListView> updates the
|
|||
|
||||
## Combine compiled bindings with classic bindings
|
||||
|
||||
Binding expressions are only compiled for the view hierarchy that the `x:DataType` attribute is defined on. Conversely, any views in a hierarchy on which the `x:DataType` attribute is not defined will use classic bindings. It's therefore possible to combine compiled bindings and classic bindings on a page. For example, in the previous section the views within the `DataTemplate` use compiled bindings, while the <xref:Microsoft.Maui.Controls.BoxView> that's set to the color selected in the <xref:Microsoft.Maui.Controls.ListView> does not.
|
||||
Binding expressions are only compiled for the view hierarchy that the `x:DataType` attribute is defined on. Conversely, any views in a hierarchy on which the `x:DataType` attribute is not defined will use classic bindings. It's therefore possible to combine compiled bindings and classic bindings on a page. For example, in the previous section the views within the <xref:Microsoft.Maui.Controls.DataTemplate> use compiled bindings, while the <xref:Microsoft.Maui.Controls.BoxView> that's set to the color selected in the <xref:Microsoft.Maui.Controls.ListView> does not.
|
||||
|
||||
Careful structuring of `x:DataType` attributes can therefore lead to a page using compiled and classic bindings. Alternatively, the `x:DataType` attribute can be re-defined at any point in a view hierarchy to `null` using the `x:Null` markup extension. Doing this indicates that any binding expressions within the view hierarchy will use classic bindings. The following example demonstrates this approach:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,11 +10,11 @@ ms.date: 01/19/2022
|
|||
|
||||
.NET Multi-platform App UI (.NET MAUI) data bindings usually transfer data from a source property to a target property, and in some cases from the target property to the source property. This transfer is straightforward when the source and target properties are of the same type, or when one type can be converted to the other type through an implicit conversion. When that is not the case, a type conversion must take place.
|
||||
|
||||
In the [String formatting](string-formatting.md) article, you saw how you can use the `StringFormat` property of a data binding to convert any type into a string. For other types of conversions, you need to write some specialized code in a class that implements the `IValueConverter` interface. Classes that implement `IValueConverter` are called *value converters*, but they are also often referred to as *binding converters* or *binding value converters*.
|
||||
In the [String formatting](string-formatting.md) article, you saw how you can use the `StringFormat` property of a data binding to convert any type into a string. For other types of conversions, you need to write some specialized code in a class that implements the <xref:Microsoft.Maui.Controls.IValueConverter> interface. Classes that implement <xref:Microsoft.Maui.Controls.IValueConverter> are called *value converters*, but they are also often referred to as *binding converters* or *binding value converters*.
|
||||
|
||||
## Binding value converters
|
||||
|
||||
Suppose you want to define a data binding where the source property is of type `int` but the target property is a `bool`. You want this data binding to produce a `false` value when the integer source is equal to 0, and `true` otherwise. This can be achieved with a class that implements the `IValueConverter` interface:
|
||||
Suppose you want to define a data binding where the source property is of type `int` but the target property is a `bool`. You want this data binding to produce a `false` value when the integer source is equal to 0, and `true` otherwise. This can be achieved with a class that implements the <xref:Microsoft.Maui.Controls.IValueConverter> interface:
|
||||
|
||||
```csharp
|
||||
public class IntToBoolConverter : IValueConverter
|
||||
|
|
@ -77,7 +77,7 @@ The following example demonstrates how to use this value converter in a data bin
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `IntToBoolConverter` is instantiated in the page's resource dictionary. It's then referenced with a `StaticResource` markup extension to set the `Converter` property in two data bindings. It is very common to share data converters among multiple data bindings on the page. If a value converter is used in multiple pages of your application, you can instantiate it in the application-level resource dictionary.
|
||||
In this example, the `IntToBoolConverter` is instantiated in the page's resource dictionary. It's then referenced with a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension to set the `Converter` property in two data bindings. It is very common to share data converters among multiple data bindings on the page. If a value converter is used in multiple pages of your application, you can instantiate it in the application-level resource dictionary.
|
||||
|
||||
This example demonstrates a common need when a <xref:Microsoft.Maui.Controls.Button> performs an operation based on text that the user types into an <xref:Microsoft.Maui.Controls.Entry> view. The `Text` property of each <xref:Microsoft.Maui.Controls.Entry> is initialized to an empty string, because the `Text` property is `null` by default, and the data binding will not work in that case. If nothing has been typed into the <xref:Microsoft.Maui.Controls.Entry>, the <xref:Microsoft.Maui.Controls.Button> should be disabled. Each <xref:Microsoft.Maui.Controls.Button> contains a data binding on its `IsEnabled` property. The data-binding source is the `Length` property of the `Text` property of the corresponding <xref:Microsoft.Maui.Controls.Entry>. If that `Length` property is not 0, the value converter returns `true` and the <xref:Microsoft.Maui.Controls.Button> is enabled:
|
||||
|
||||
|
|
@ -227,7 +227,7 @@ In this example, in the last of the three <xref:Microsoft.Maui.Controls.Switch>
|
|||
|
||||
The `Binding` class defines a `ConverterParameter` property, and the `Binding` markup extension also defines a `ConverterParameter` property. If this property is set, then the value is passed to the `Convert` and `ConvertBack` methods as the `parameter` argument. Even if the instance of the value converter is shared among several data bindings, the `ConverterParameter` can be different to perform different conversions.
|
||||
|
||||
The use of the `ConverterParameter` property can be demonstrated with a color-selection program. The following example shows the `RgbColorViewModel`, which has three properties of type `float` named `Red`, `Green`, and `Blue` that it uses to construct a `Color` value:
|
||||
The use of the `ConverterParameter` property can be demonstrated with a color-selection program. The following example shows the `RgbColorViewModel`, which has three properties of type `float` named `Red`, `Green`, and `Blue` that it uses to construct a <xref:Microsoft.Maui.Graphics.Color> value:
|
||||
|
||||
```csharp
|
||||
public class RgbColorViewModel : INotifyPropertyChanged
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ In addition, the `MultiBinding` class inherits the following properties from the
|
|||
- `StringFormat`, of type `string`, which specifies how to format the multi-binding result if it's displayed as a string.
|
||||
- `TargetNullValue`, of type `object`, which represents the value that's used in the target when the value of the source is `null`.
|
||||
|
||||
A `MultiBinding` must use a `IMultiValueConverter` to produce a value for the binding target, based on the value of the bindings in the `Bindings` collection. For example, a `Color` might be computed from red, blue, and green values, which can be values from the same or different binding source objects. When a value moves from the target to the sources, the target property value is translated to a set of values that are fed back into the bindings.
|
||||
A `MultiBinding` must use a `IMultiValueConverter` to produce a value for the binding target, based on the value of the bindings in the `Bindings` collection. For example, a <xref:Microsoft.Maui.Graphics.Color> might be computed from red, blue, and green values, which can be values from the same or different binding source objects. When a value moves from the target to the sources, the target property value is translated to a set of values that are fed back into the bindings.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Individual bindings in the `Bindings` collection can have their own value converters.
|
||||
|
|
@ -114,7 +114,7 @@ The `ConvertBack` method returns an array of values of type `object[]` that have
|
|||
|
||||
## Consume a IMultiValueConverter
|
||||
|
||||
A `IMultiValueConverter` is typically consumed by instantiating it in a resource dictionary, and then referencing it using the `StaticResource` markup extension to set the `MultiBinding.Converter` property:
|
||||
A `IMultiValueConverter` is typically consumed by instantiating it in a resource dictionary, and then referencing it using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension to set the `MultiBinding.Converter` property:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -303,6 +303,6 @@ In this example, the `MultiBinding` object uses its `AnyTrueMultiConverter` inst
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `TemplatedParent` relative binding mode is used to bind from within a control template to the runtime object instance to which the template is applied. The `Expander`, which is the root element of the `ControlTemplate`, has its `BindingContext` set to the runtime object instance to which the template is applied. Therefore, the `Expander` and its children resolve their binding expressions, and `Binding` objects, against the properties of the `CardViewExpander` object. The `MultiBinding` uses the `AllTrueMultiConverter` instance to set the `Expander.IsVisible` property to `true` provided that the two `Binding` objects evaluate to `true`. Otherwise, the `Expander.IsVisible` property is set to `false`.
|
||||
In this example, the `TemplatedParent` relative binding mode is used to bind from within a control template to the runtime object instance to which the template is applied. The `Expander`, which is the root element of the <xref:Microsoft.Maui.Controls.ControlTemplate>, has its `BindingContext` set to the runtime object instance to which the template is applied. Therefore, the `Expander` and its children resolve their binding expressions, and `Binding` objects, against the properties of the `CardViewExpander` object. The `MultiBinding` uses the `AllTrueMultiConverter` instance to set the `Expander.IsVisible` property to `true` provided that the two `Binding` objects evaluate to `true`. Otherwise, the `Expander.IsVisible` property is set to `false`.
|
||||
|
||||
For more information about relative bindings, see [Relative bindings](relative-bindings.md). For more information about control templates, see [Control templates](~/fundamentals/controltemplate.md).
|
||||
|
|
|
|||
|
|
@ -8,16 +8,16 @@ ms.date: 01/19/2022
|
|||
|
||||
[ Browse the sample](/samples/dotnet/maui-samples/fundamentals-databinding)
|
||||
|
||||
.NET Multi-platform App UI (.NET MAUI) relative bindings provide the ability to set the binding source relative to the position of the binding target. They are created with the `RelativeSource` markup extension, and set as the `Source` property of a binding expression.
|
||||
.NET Multi-platform App UI (.NET MAUI) relative bindings provide the ability to set the binding source relative to the position of the binding target. They are created with the [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension, and set as the `Source` property of a binding expression.
|
||||
|
||||
The `RelativeSource` markup extension is supported by the `RelativeSourceExtension` class, which defines the following properties:
|
||||
The [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) markup extension is supported by the `RelativeSourceExtension` class, which defines the following properties:
|
||||
|
||||
- `Mode`, of type `RelativeBindingSourceMode`, describes the location of the binding source relative to the position of the binding target.
|
||||
- `AncestorLevel`, of type `int`, an optional ancestor level to look for, when the `Mode` property is `FindAncestor`. An `AncestorLevel` of `n` skips `n-1` instances of the `AncestorType`.
|
||||
- `AncestorType`, of type `Type`, the type of ancestor to look for, when the `Mode` property is `FindAncestor`.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `RelativeSourceExtension` class to be abbreviated as `RelativeSource`.
|
||||
> The XAML parser allows the `RelativeSourceExtension` class to be abbreviated as [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension).
|
||||
|
||||
The `Mode` property should be set to one of the `RelativeBindingSourceMode` enumeration members:
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ The following XAML shows an example where the `Mode` property will be implicitly
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `BindingContext` of the page is set to the `DefaultViewModel` property of itself. This property is defined in the code-behind file for the page, and provides a viewmodel instance. The <xref:Microsoft.Maui.Controls.ListView> binds to the `Employees` property of the viewmodel. The `DataTemplate`, which defines the appearance of each item in the <xref:Microsoft.Maui.Controls.ListView>, contains a <xref:Microsoft.Maui.Controls.Button>. The button's `Command` property is bound to the `DeleteEmployeeCommand` in its parent's viewmodel. Tapping a <xref:Microsoft.Maui.Controls.Button> deletes an employee:
|
||||
In this example, the `BindingContext` of the page is set to the `DefaultViewModel` property of itself. This property is defined in the code-behind file for the page, and provides a viewmodel instance. The <xref:Microsoft.Maui.Controls.ListView> binds to the `Employees` property of the viewmodel. The <xref:Microsoft.Maui.Controls.DataTemplate>, which defines the appearance of each item in the <xref:Microsoft.Maui.Controls.ListView>, contains a <xref:Microsoft.Maui.Controls.Button>. The button's `Command` property is bound to the `DeleteEmployeeCommand` in its parent's viewmodel. Tapping a <xref:Microsoft.Maui.Controls.Button> deletes an employee:
|
||||
|
||||
:::image type="content" source="media/relative-bindings/findancestor-relative-binding.png" alt-text="Screenshot of a FindAncestor mode relative binding.":::
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ The following XAML shows an example of the `TemplatedParent` relative binding mo
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Frame>, which is the root element of the `ControlTemplate`, has its `BindingContext` set to the runtime object instance to which the template is applied. Therefore, the <xref:Microsoft.Maui.Controls.Frame> and its children resolve their binding expressions against the properties of each `CardView` object:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.Frame>, which is the root element of the <xref:Microsoft.Maui.Controls.ControlTemplate>, has its `BindingContext` set to the runtime object instance to which the template is applied. Therefore, the <xref:Microsoft.Maui.Controls.Frame> and its children resolve their binding expressions against the properties of each `CardView` object:
|
||||
|
||||
:::image type="content" source="media/relative-bindings/templatedparent-relative-binding.png" alt-text="Screenshot of a TemplatedParent mode relative binding.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ The `Person` class defines `Name`, `Age`, and `Location` properties, which can b
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, items are added to the <xref:Microsoft.Maui.Controls.CollectionView> by initializing its `ItemsSource` property from an array of `Person` objects. <xref:Microsoft.Maui.Controls.CollectionView> calls `ToString` when displaying the objects in the collection. However, because there is no `Person.ToString` override, `ToString` returns the type name of each object:
|
||||
In this example, items are added to the <xref:Microsoft.Maui.Controls.CollectionView> by initializing its <xref:Microsoft.Maui.Controls.ItemsView.ItemsSource> property from an array of `Person` objects. <xref:Microsoft.Maui.Controls.CollectionView> calls `ToString` when displaying the objects in the collection. However, because there is no `Person.ToString` override, `ToString` returns the type name of each object:
|
||||
|
||||
:::image type="content" source="media/datatemplate/no-data-template.png" alt-text="Screenshot of a CollectionView without a data template.":::
|
||||
|
||||
|
|
@ -66,26 +66,26 @@ This results in the <xref:Microsoft.Maui.Controls.CollectionView> displaying the
|
|||
|
||||
:::image type="content" source="media/datatemplate/override-tostring.png" alt-text="Screenshot of a CollectionView that overrides the Person.ToString method.":::
|
||||
|
||||
The `Person.ToString` override could return a formatted string consisting of the `Name`, `Age`, and `Location` properties. However, this approach only offers limited control over the appearance of each item of data. For more flexibility, a `DataTemplate` can be created that defines the appearance of the data.
|
||||
The `Person.ToString` override could return a formatted string consisting of the `Name`, `Age`, and `Location` properties. However, this approach only offers limited control over the appearance of each item of data. For more flexibility, a <xref:Microsoft.Maui.Controls.DataTemplate> can be created that defines the appearance of the data.
|
||||
|
||||
## Create a DataTemplate
|
||||
|
||||
A `DataTemplate` is used to specify the appearance of data, and typically uses data binding to display data. A common usage scenario for data templates is when displaying data from a collection of objects in a control such as a <xref:Microsoft.Maui.Controls.CollectionView> or <xref:Microsoft.Maui.Controls.CarouselView>. For example, when a <xref:Microsoft.Maui.Controls.CollectionView> is bound to a collection of `Person` objects, the `CollectionView.ItemTemplate` property can be set to a `DataTemplate` that defines the appearance of each `Person` object in the <xref:Microsoft.Maui.Controls.CollectionView>. The `DataTemplate` will contain objects that bind to property values of each `Person` object. For more information about data binding, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplate> is used to specify the appearance of data, and typically uses data binding to display data. A common usage scenario for data templates is when displaying data from a collection of objects in a control such as a <xref:Microsoft.Maui.Controls.CollectionView> or <xref:Microsoft.Maui.Controls.CarouselView>. For example, when a <xref:Microsoft.Maui.Controls.CollectionView> is bound to a collection of `Person` objects, the <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property can be set to a <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each `Person` object in the <xref:Microsoft.Maui.Controls.CollectionView>. The <xref:Microsoft.Maui.Controls.DataTemplate> will contain objects that bind to property values of each `Person` object. For more information about data binding, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
|
||||
A `DataTemplate` that's defined inline in a control is known as an *inline template*. Alternatively, data templates can be defined as a control-level, page-level, or app-level resource. Choosing where to define a `DataTemplate` impacts where it can be used:
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplate> that's defined inline in a control is known as an *inline template*. Alternatively, data templates can be defined as a control-level, page-level, or app-level resource. Choosing where to define a <xref:Microsoft.Maui.Controls.DataTemplate> impacts where it can be used:
|
||||
|
||||
- A `DataTemplate` defined at the control-level can only be applied to the control.
|
||||
- A `DataTemplate` defined at the page-level can be applied to multiple controls on the page.
|
||||
- A `DataTemplate` defined at the app-level can be applied to valid controls throughout the app.
|
||||
- A <xref:Microsoft.Maui.Controls.DataTemplate> defined at the control-level can only be applied to the control.
|
||||
- A <xref:Microsoft.Maui.Controls.DataTemplate> defined at the page-level can be applied to multiple controls on the page.
|
||||
- A <xref:Microsoft.Maui.Controls.DataTemplate> defined at the app-level can be applied to valid controls throughout the app.
|
||||
|
||||
> [!NOTE]
|
||||
> Data templates lower in the view hierarchy take precedence over those defined higher up when they share `x:Key` attributes. For example, an app-level data template will be overridden by a page-level data template, and a page-level data template will be overridden by a control-level data template, or an inline data template.
|
||||
|
||||
A `DataTemplate` can be created inline, with a type, or as a resource, regardless of where it's defined.
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplate> can be created inline, with a type, or as a resource, regardless of where it's defined.
|
||||
|
||||
### Create an inline DataTemplate
|
||||
|
||||
An inline data template, which is one that's defined inline in a control, should be used if there's no need to reuse the data template elsewhere. The objects specified in the `DataTemplate` define the appearance of each item of data. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its `ItemTemplate` property to the inline `DataTemplate`:
|
||||
An inline data template, which is one that's defined inline in a control, should be used if there's no need to reuse the data template elsewhere. The objects specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each item of data. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property to the inline <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CollectionView>
|
||||
|
|
@ -112,13 +112,13 @@ An inline data template, which is one that's defined inline in a control, should
|
|||
</CollectionView>
|
||||
```
|
||||
|
||||
In a <xref:Microsoft.Maui.Controls.CollectionView>, the child of an inline `DataTemplate` must derive from <xref:Microsoft.Maui.Controls.BindableObject>. In this example, a <xref:Microsoft.Maui.Controls.Grid>, which derives from <xref:Microsoft.Maui.Controls.Layout> is used. The <xref:Microsoft.Maui.Controls.Grid> contains three <xref:Microsoft.Maui.Controls.Label> objects that bind their `Text` properties to properties of each `Person` object in the collection. The following screenshot shows the resulting appearance:
|
||||
In a <xref:Microsoft.Maui.Controls.CollectionView>, the child of an inline <xref:Microsoft.Maui.Controls.DataTemplate> must derive from <xref:Microsoft.Maui.Controls.BindableObject>. In this example, a <xref:Microsoft.Maui.Controls.Grid>, which derives from <xref:Microsoft.Maui.Controls.Layout> is used. The <xref:Microsoft.Maui.Controls.Grid> contains three <xref:Microsoft.Maui.Controls.Label> objects that bind their `Text` properties to properties of each `Person` object in the collection. The following screenshot shows the resulting appearance:
|
||||
|
||||
:::image type="content" source="media/datatemplate/data-template-appearance.png" alt-text="Screenshot of a CollectionView with a data template.":::
|
||||
|
||||
### Create a DataTemplate with a type
|
||||
|
||||
A `DataTemplate` can be created with a custom view type. The advantage of this approach is that the appearance defined by the view can be reused by multiple data templates throughout an app. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its `ItemTemplate` property to the `DataTemplate`:
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplate> can be created with a custom view type. The advantage of this approach is that the appearance defined by the view can be reused by multiple data templates throughout an app. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property to the <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -143,7 +143,7 @@ A `DataTemplate` can be created with a custom view type. The advantage of this a
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `CollectionView.ItemTemplate` property is set to a `DataTemplate` that's created from a custom type that defines the view appearance. The custom type must derive from <xref:Microsoft.Maui.Controls.ContentView>:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property is set to a <xref:Microsoft.Maui.Controls.DataTemplate> that's created from a custom type that defines the view appearance. The custom type must derive from <xref:Microsoft.Maui.Controls.ContentView>:
|
||||
|
||||
```xaml
|
||||
<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -168,7 +168,7 @@ For more information about creating custom views, see [ContentView](~/user-inter
|
|||
|
||||
### Create a DataTemplate as a resource
|
||||
|
||||
Data templates can be created as reusable objects in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. This is achieved by giving each `DataTemplate` a unique `x:Key` value, which provides it with a descriptive key in the <xref:Microsoft.Maui.Controls.ResourceDictionary>. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its `ItemTemplate` property to the `DataTemplate`:
|
||||
Data templates can be created as reusable objects in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. This is achieved by giving each <xref:Microsoft.Maui.Controls.DataTemplate> a unique `x:Key` value, which provides it with a descriptive key in the <xref:Microsoft.Maui.Controls.ResourceDictionary>. A control such as <xref:Microsoft.Maui.Controls.CollectionView> can then set its <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property to the <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -198,13 +198,13 @@ Data templates can be created as reusable objects in a <xref:Microsoft.Maui.Cont
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the `DataTemplate` is assigned to the `CollectionView.ItemTemplate` property by using the `StaticResource` markup extension. While the `DataTemplate` is defined in the page's <xref:Microsoft.Maui.Controls.ResourceDictionary>, it could also be defined at the control-level or app-level.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.DataTemplate> is assigned to the <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property by using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension. While the <xref:Microsoft.Maui.Controls.DataTemplate> is defined in the page's <xref:Microsoft.Maui.Controls.ResourceDictionary>, it could also be defined at the control-level or app-level.
|
||||
|
||||
## Create a DataTemplateSelector
|
||||
|
||||
A `DataTemplateSelector` can be used to choose a `DataTemplate` at runtime based on the value of a data-bound property. This enables multiple data templates to be applied to the same type of object, to choose their appearance at runtime. A data template selector enables scenarios such as a <xref:Microsoft.Maui.Controls.CollectionView> or <xref:Microsoft.Maui.Controls.CarouselView> binding to a collection of objects where the appearance of each object can be chosen at runtime by the data template selector returning a specific `DataTemplate`.
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplateSelector> can be used to choose a <xref:Microsoft.Maui.Controls.DataTemplate> at runtime based on the value of a data-bound property. This enables multiple data templates to be applied to the same type of object, to choose their appearance at runtime. A data template selector enables scenarios such as a <xref:Microsoft.Maui.Controls.CollectionView> or <xref:Microsoft.Maui.Controls.CarouselView> binding to a collection of objects where the appearance of each object can be chosen at runtime by the data template selector returning a specific <xref:Microsoft.Maui.Controls.DataTemplate>.
|
||||
|
||||
A data template selector is implemented by creating a class that inherits from `DataTemplateSelector`. The `OnSelectTemplate` method should then be overridden to return a specific `DataTemplate`:
|
||||
A data template selector is implemented by creating a class that inherits from <xref:Microsoft.Maui.Controls.DataTemplateSelector>. The <xref:Microsoft.Maui.Controls.DataTemplateSelector.OnSelectTemplate%2A> method should then be overridden to return a specific <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```csharp
|
||||
public class PersonDataTemplateSelector : DataTemplateSelector
|
||||
|
|
@ -219,19 +219,19 @@ public class PersonDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
In this example, the `OnSelectTemplate` method returns a specific data template based on the value of the `DateOfBirth` property. The returned data template is defined by the `ValidTemplate` or `InvalidTemplate` property, which are set when consuming the data template selector.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.DataTemplateSelector.OnSelectTemplate%2A> method returns a specific data template based on the value of the `DateOfBirth` property. The returned data template is defined by the `ValidTemplate` or `InvalidTemplate` property, which are set when consuming the data template selector.
|
||||
|
||||
### Limitations
|
||||
|
||||
`DataTemplateSelector` objects have the following limitations:
|
||||
<xref:Microsoft.Maui.Controls.DataTemplateSelector> objects have the following limitations:
|
||||
|
||||
- The `DataTemplateSelector` subclass must always return the same template for the same data if queried multiple times.
|
||||
- The `DataTemplateSelector` subclass must not return another `DataTemplateSelector` subclass.
|
||||
- The `DataTemplateSelector` subclass must not return new instances of a `DataTemplate` on each call. Instead, the same instance must be returned. Failure to do so will create a memory leak and will disable control virtualization.
|
||||
- The <xref:Microsoft.Maui.Controls.DataTemplateSelector> subclass must always return the same template for the same data if queried multiple times.
|
||||
- The <xref:Microsoft.Maui.Controls.DataTemplateSelector> subclass must not return another <xref:Microsoft.Maui.Controls.DataTemplateSelector> subclass.
|
||||
- The <xref:Microsoft.Maui.Controls.DataTemplateSelector> subclass must not return new instances of a <xref:Microsoft.Maui.Controls.DataTemplate> on each call. Instead, the same instance must be returned. Failure to do so will create a memory leak and will disable control virtualization.
|
||||
|
||||
### Consume a DataTemplateSelector
|
||||
|
||||
A data template selector can be consumed by creating it as a resource and assigning its instance to .NET MAUI control properties of type `DataTemplate`, such as `CollectionView.ItemTemplate`.
|
||||
A data template selector can be consumed by creating it as a resource and assigning its instance to .NET MAUI control properties of type <xref:Microsoft.Maui.Controls.DataTemplate>, such as <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate>.
|
||||
|
||||
The following example shows declaring `PersonDataTemplateSelector` as a page-level resource:
|
||||
|
||||
|
|
@ -259,16 +259,16 @@ The following example shows declaring `PersonDataTemplateSelector` as a page-lev
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the page-level <xref:Microsoft.Maui.Controls.ResourceDictionary> defines two `DataTemplate` objects and a `PersonDataTemplateSelector` object. The `PersonDataTemplateSelector` object sets its `ValidTemplate` and `InvalidTemplate` properties to the `DataTemplate` objects using the `StaticResource` markup extension. While the resources are defined in the page's <xref:Microsoft.Maui.Controls.ResourceDictionary>, they could also be defined at the control-level or app-level.
|
||||
In this example, the page-level <xref:Microsoft.Maui.Controls.ResourceDictionary> defines two <xref:Microsoft.Maui.Controls.DataTemplate> objects and a `PersonDataTemplateSelector` object. The `PersonDataTemplateSelector` object sets its `ValidTemplate` and `InvalidTemplate` properties to the <xref:Microsoft.Maui.Controls.DataTemplate> objects using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension. While the resources are defined in the page's <xref:Microsoft.Maui.Controls.ResourceDictionary>, they could also be defined at the control-level or app-level.
|
||||
|
||||
The `PersonDataTemplateSelector` object can be consumed by assigning it to the `CollectionView.ItemTemplate` property:
|
||||
The `PersonDataTemplateSelector` object can be consumed by assigning it to the <xref:Microsoft.Maui.Controls.ItemsView.ItemTemplate> property:
|
||||
|
||||
```xaml
|
||||
<CollectionView x:Name="collectionView"
|
||||
ItemTemplate="{StaticResource personDataTemplateSelector}" />
|
||||
```
|
||||
|
||||
At runtime, the <xref:Microsoft.Maui.Controls.CollectionView> calls the `PersonDataTemplateSelector.OnSelectTemplate` method for each of the items in the underlying collection, with the call passing the data object as the `item` parameter. The returned `DataTemplate` is then applied to that object.
|
||||
At runtime, the <xref:Microsoft.Maui.Controls.CollectionView> calls the `PersonDataTemplateSelector.OnSelectTemplate` method for each of the items in the underlying collection, with the call passing the data object as the `item` parameter. The returned <xref:Microsoft.Maui.Controls.DataTemplate> is then applied to that object.
|
||||
|
||||
The following screenshot shows the result of the <xref:Microsoft.Maui.Controls.CollectionView> applying the `PersonDataTemplateSelector` to each object in the underlying collection:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ ms.date: 01/28/2022
|
|||
|
||||
A .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.ResourceDictionary> is a repository for resources that are used by a .NET MAUI app. Typical resources that are stored in a <xref:Microsoft.Maui.Controls.ResourceDictionary> include styles, control templates, data templates, converters, and colors.
|
||||
|
||||
XAML resources that are stored in a <xref:Microsoft.Maui.Controls.ResourceDictionary> can be referenced and applied to elements by using the `StaticResource` or `DynamicResource` markup extension. In C#, resources can also be defined in a <xref:Microsoft.Maui.Controls.ResourceDictionary> and then referenced and applied to elements by using a string-based indexer. However, there's little advantage to using a <xref:Microsoft.Maui.Controls.ResourceDictionary> in C#, as shared objects can be stored as fields or properties, and accessed directly without having to first retrieve them from a dictionary.
|
||||
XAML resources that are stored in a <xref:Microsoft.Maui.Controls.ResourceDictionary> can be referenced and applied to elements by using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) or [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension. In C#, resources can also be defined in a <xref:Microsoft.Maui.Controls.ResourceDictionary> and then referenced and applied to elements by using a string-based indexer. However, there's little advantage to using a <xref:Microsoft.Maui.Controls.ResourceDictionary> in C#, as shared objects can be stored as fields or properties, and accessed directly without having to first retrieve them from a dictionary.
|
||||
|
||||
> [!TIP]
|
||||
> In Visual Studio, a XAML-based <xref:Microsoft.Maui.Controls.ResourceDictionary> file that's backed by a code-behind file can be added to your project by the **.NET MAUI ResourceDictionary (XAML)** item template.
|
||||
|
|
@ -60,16 +60,16 @@ The following XAML shows resources defined in an application level <xref:Microso
|
|||
</Application>
|
||||
```
|
||||
|
||||
In this example, the resource dictionary defines a `Thickness` resource, multiple `Color` resources, and two implicit <xref:Microsoft.Maui.Controls.Style> resources.<!-- For more information about the `App` class, see [.NET MAUI App Class](~/fundamentals/application-class.md).-->
|
||||
In this example, the resource dictionary defines a `Thickness` resource, multiple <xref:Microsoft.Maui.Graphics.Color> resources, and two implicit <xref:Microsoft.Maui.Controls.Style> resources.<!-- For more information about the `App` class, see [.NET MAUI App Class](~/fundamentals/application-class.md).-->
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Inserting resources directly between the `Resources` property-element tags automatically creates a <xref:Microsoft.Maui.Controls.ResourceDictionary> object. However, it's also valid to place all resources between optional <xref:Microsoft.Maui.Controls.ResourceDictionary> tags.
|
||||
|
||||
## Consume resources
|
||||
|
||||
Each resource has a key that is specified using the `x:Key` attribute, which becomes its dictionary key in the <xref:Microsoft.Maui.Controls.ResourceDictionary>. The key is used to reference a resource from the <xref:Microsoft.Maui.Controls.ResourceDictionary> with the `StaticResource` or `DynamicResource` XAML markup extension.
|
||||
Each resource has a key that is specified using the `x:Key` attribute, which becomes its dictionary key in the <xref:Microsoft.Maui.Controls.ResourceDictionary>. The key is used to reference a resource from the <xref:Microsoft.Maui.Controls.ResourceDictionary> with the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) or [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) XAML markup extension.
|
||||
|
||||
The `StaticResource` markup extension is similar to the `DynamicResource` markup extension in that both use a dictionary key to reference a value from a resource dictionary. However, while the `StaticResource` markup extension performs a single dictionary lookup, the `DynamicResource` markup extension maintains a link to the dictionary key. Therefore, if the dictionary entry associated with the key is replaced, the change is applied to the visual element. This enables runtime resource changes to be made in an app. For more information about markup extensions, see [XAML markup extensions](~/xaml/markup-extensions/consume.md).
|
||||
The [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension is similar to the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension in that both use a dictionary key to reference a value from a resource dictionary. However, while the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension performs a single dictionary lookup, the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension maintains a link to the dictionary key. Therefore, if the dictionary entry associated with the key is replaced, the change is applied to the visual element. This enables runtime resource changes to be made in an app. For more information about markup extensions, see [XAML markup extensions](~/xaml/markup-extensions/consume.md).
|
||||
|
||||
The following XAML example shows how to consume resources, and also define an additional resource in a <xref:Microsoft.Maui.Controls.StackLayout>:
|
||||
|
||||
|
|
@ -106,14 +106,14 @@ In this example, the <xref:Microsoft.Maui.Controls.ContentPage> object consumes
|
|||
|
||||
## Resource lookup behavior
|
||||
|
||||
The following lookup process occurs when a resource is referenced with the `StaticResource` or `DynamicResource` markup extension:
|
||||
The following lookup process occurs when a resource is referenced with the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) or [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension:
|
||||
|
||||
- The requested key is checked for in the resource dictionary, if it exists, for the element that sets the property. If the requested key is found, its value is returned and the lookup process terminates.
|
||||
- If a match isn't found, the lookup process searches the visual tree upwards, checking the resource dictionary of each parent element. If the requested key is found, its value is returned and the lookup process terminates. Otherwise the process continues upwards until the root element is reached.
|
||||
- If a match isn't found at the root element, the application level resource dictionary is examined.
|
||||
- If a match still isn't found, a `XamlParseException` is thrown.
|
||||
|
||||
Therefore, when the XAML parser encounters a `StaticResource` or `DynamicResource` markup extension, it searches for a matching key by traveling up through the visual tree, using the first match it finds. If this search ends at the page and the key still hasn't been found, the XAML parser searches the <xref:Microsoft.Maui.Controls.ResourceDictionary> attached to the `App` object. If the key still isn't found, an exception is thrown.
|
||||
Therefore, when the XAML parser encounters a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) or [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension, it searches for a matching key by traveling up through the visual tree, using the first match it finds. If this search ends at the page and the key still hasn't been found, the XAML parser searches the <xref:Microsoft.Maui.Controls.ResourceDictionary> attached to the `App` object. If the key still isn't found, an exception is thrown.
|
||||
|
||||
## Override resources
|
||||
|
||||
|
|
@ -158,7 +158,7 @@ The following XAML example shows a stand-alone <xref:Microsoft.Maui.Controls.Res
|
|||
</ResourceDictionary>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> contains a single resource, which is an object of type `DataTemplate`. **MyResourceDictionary.xaml** can be consumed by merging it into another resource dictionary.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> contains a single resource, which is an object of type <xref:Microsoft.Maui.Controls.DataTemplate>. **MyResourceDictionary.xaml** can be consumed by merging it into another resource dictionary.
|
||||
|
||||
<!--
|
||||
By default, the linker will remove stand-alone XAML files from release builds when the linker behavior is set to link all assemblies. To ensure that stand-alone XAML files remain in a release build:
|
||||
|
|
|
|||
|
|
@ -72,4 +72,4 @@ Pressing the hamburger icon, or swiping from the left, displays the flyout:
|
|||
Multiple items are displayed on the flyout because the <xref:Microsoft.Maui.Controls.FlyoutDisplayOptions> property is set to `AsMultipleItems`. For more information, see [Flyout display options](flyout.md#flyout-display-options).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the `DataTemplate` markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the <xref:Microsoft.Maui.Controls.DataTemplate> markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ The `FlyoutItem.Title` property, of type `string`, defines the title of the flyo
|
|||
In this example, each <xref:Microsoft.Maui.Controls.ShellContent> object can only be accessed through flyout items, and not through tabs. This is because by default, tabs will only be displayed if the flyout item contains more than one tab.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the `DataTemplate` markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the <xref:Microsoft.Maui.Controls.DataTemplate> markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
|
||||
Shell has implicit conversion operators that enable the Shell visual hierarchy to be simplified, without introducing additional views into the visual tree. This is possible because a subclassed <xref:Microsoft.Maui.Controls.Shell> object can only ever contain <xref:Microsoft.Maui.Controls.FlyoutItem> objects or a <xref:Microsoft.Maui.Controls.TabBar> object, which can only ever contain <xref:Microsoft.Maui.Controls.Tab> objects, which can only ever contain <xref:Microsoft.Maui.Controls.ShellContent> objects. These implicit conversion operators can be used to remove the <xref:Microsoft.Maui.Controls.FlyoutItem> and <xref:Microsoft.Maui.Controls.Tab> objects from the previous example:
|
||||
|
||||
|
|
@ -125,7 +125,7 @@ This results in the following flyout items:
|
|||
|
||||
### Define FlyoutItem appearance
|
||||
|
||||
The appearance of each <xref:Microsoft.Maui.Controls.FlyoutItem> can be customized by setting the `Shell.ItemTemplate` attached property to a `DataTemplate`:
|
||||
The appearance of each <xref:Microsoft.Maui.Controls.FlyoutItem> can be customized by setting the `Shell.ItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
@ -159,7 +159,7 @@ In addition, Shell includes three style classes, which are automatically applied
|
|||
|
||||
### Default template for FlyoutItems
|
||||
|
||||
The default `DataTemplate` used for each <xref:Microsoft.Maui.Controls.FlyoutItem> is shown below:
|
||||
The default <xref:Microsoft.Maui.Controls.DataTemplate> used for each <xref:Microsoft.Maui.Controls.FlyoutItem> is shown below:
|
||||
|
||||
```xaml
|
||||
<DataTemplate x:Key="FlyoutTemplate">
|
||||
|
|
@ -277,7 +277,7 @@ In this example, the flyout content is replaced with a <xref:Microsoft.Maui.Cont
|
|||
> [!NOTE]
|
||||
> The `FlyoutItems` property, in the <xref:Microsoft.Maui.Controls.Shell> class, is a read-only collection of flyout items.
|
||||
|
||||
Alternatively, flyout content can be defined by setting the `Shell.FlyoutContentTemplate` bindable property to a `DataTemplate`:
|
||||
Alternatively, flyout content can be defined by setting the `Shell.FlyoutContentTemplate` bindable property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...
|
||||
|
|
@ -333,7 +333,7 @@ The `MenuItem` object executes an `ICommand` named `HelpCommand`, which opens th
|
|||
|
||||
### Define MenuItem appearance
|
||||
|
||||
The appearance of each `MenuItem` can be customized by setting the `Shell.MenuItemTemplate` attached property to a `DataTemplate`:
|
||||
The appearance of each `MenuItem` can be customized by setting the `Shell.MenuItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
@ -358,7 +358,7 @@ The appearance of each `MenuItem` can be customized by setting the `Shell.MenuIt
|
|||
</Shell>
|
||||
```
|
||||
|
||||
This example attaches the `DataTemplate` to each `MenuItem` object, displaying the title of the `MenuItem` object in italics:
|
||||
This example attaches the <xref:Microsoft.Maui.Controls.DataTemplate> to each `MenuItem` object, displaying the title of the `MenuItem` object in italics:
|
||||
|
||||
:::image type="content" source="media/flyout/menuitem-templated.png" alt-text="Screenshot of templated MenuItem objects.":::
|
||||
|
||||
|
|
@ -438,7 +438,7 @@ This results in the following flyout header:
|
|||
|
||||
:::image type="content" source="media/flyout/flyout-header.png" alt-text="Screenshot of the flyout header.":::
|
||||
|
||||
Alternatively, the flyout header appearance can be defined by setting the `Shell.FlyoutHeaderTemplate` bindable property to a `DataTemplate`:
|
||||
Alternatively, the flyout header appearance can be defined by setting the `Shell.FlyoutHeaderTemplate` bindable property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
@ -514,7 +514,7 @@ This results in the following flyout footer:
|
|||
|
||||
:::image type="content" source="media/flyout/flyout-footer.png" alt-text="Screenshot of the flyout footer.":::
|
||||
|
||||
Alternatively, the flyout footer appearance can be defined by setting the `Shell.FlyoutFooterTemplate` property to a `DataTemplate`:
|
||||
Alternatively, the flyout footer appearance can be defined by setting the `Shell.FlyoutFooterTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<Shell ...>
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ In addition, the <xref:Microsoft.Maui.Controls.Shell> class defines attached pro
|
|||
|
||||
## Display pages
|
||||
|
||||
In .NET MAUI Shell apps, pages are typically created on demand in response to navigation. This is accomplished by using the `DataTemplate` markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object:
|
||||
In .NET MAUI Shell apps, pages are typically created on demand in response to navigation. This is accomplished by using the <xref:Microsoft.Maui.Controls.DataTemplate> markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object:
|
||||
|
||||
```xaml
|
||||
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -84,11 +84,11 @@ In this example, `CatsPage`, `DogsPage`, and `MonkeysPage` are all created at ap
|
|||
|
||||
The <xref:Microsoft.Maui.Controls.Shell> class defines the following attached properties that can be used to set page colors in a Shell app:
|
||||
|
||||
- `BackgroundColor`, of type `Color`, that defines the background color in the Shell chrome. The color will not fill in behind the Shell content.
|
||||
- `DisabledColor`, of type `Color`, that defines the color to shade text and icons that are disabled.
|
||||
- `ForegroundColor`, of type `Color`, that defines the color to shade text and icons.
|
||||
- `TitleColor`, of type `Color`, that defines the color used for the title of the current page.
|
||||
- `UnselectedColor`, of type `Color`, that defines the color used for unselected text and icons in the Shell chrome.
|
||||
- `BackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the background color in the Shell chrome. The color will not fill in behind the Shell content.
|
||||
- `DisabledColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the color to shade text and icons that are disabled.
|
||||
- `ForegroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the color to shade text and icons.
|
||||
- `TitleColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the color used for the title of the current page.
|
||||
- `UnselectedColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the color used for unselected text and icons in the Shell chrome.
|
||||
|
||||
All of these properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which mean that the properties can be targets of data bindings, and styled using XAML styles. In addition, the properties can be set using Cascading Style Sheets (CSS). For more information, see [.NET MAUI Shell specific properties](~/user-interface/styles/css.md#net-maui-shell-specific-properties).
|
||||
|
||||
|
|
|
|||
|
|
@ -113,7 +113,7 @@ When a search result is selected, the `MonkeyDetailPage` is navigated to, and a
|
|||
|
||||
## Define search results item appearance
|
||||
|
||||
In addition to displaying `string` data in the search results, the appearance of each search result item can be defined by setting the `SearchHandler.ItemTemplate` property to a `DataTemplate`:
|
||||
In addition to displaying `string` data in the search results, the appearance of each search result item can be defined by setting the `SearchHandler.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -141,7 +141,7 @@ In addition to displaying `string` data in the search results, the appearance of
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
The elements specified in the `DataTemplate` define the appearance of each item in the suggestions area. In this example, layout within the `DataTemplate` is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and a <xref:Microsoft.Maui.Controls.Label> object, that both bind to properties of each `Monkey` object.
|
||||
The elements specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each item in the suggestions area. In this example, layout within the <xref:Microsoft.Maui.Controls.DataTemplate> is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and a <xref:Microsoft.Maui.Controls.Label> object, that both bind to properties of each `Monkey` object.
|
||||
|
||||
The following screenshot shows the result of templating each item in the suggestions area:
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Shell has implicit-conversion operators that enable the Shell visual hierarchy t
|
|||
This implicit conversion automatically wraps the <xref:Microsoft.Maui.Controls.ShellContent> object in a <xref:Microsoft.Maui.Controls.Tab> object, which is wrapped in a <xref:Microsoft.Maui.Controls.TabBar> object.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the `DataTemplate` markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the <xref:Microsoft.Maui.Controls.DataTemplate> markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
|
||||
## Bottom tabs
|
||||
|
||||
|
|
@ -105,7 +105,7 @@ In addition, Shell's implicit conversion operators can be used to remove the <xr
|
|||
This implicit conversion automatically wraps each <xref:Microsoft.Maui.Controls.ShellContent> object in a <xref:Microsoft.Maui.Controls.Tab> object.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the `DataTemplate` markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
> In a Shell app, pages are created on demand in response to navigation. This is accomplished by using the <xref:Microsoft.Maui.Controls.DataTemplate> markup extension to set the `ContentTemplate` property of each <xref:Microsoft.Maui.Controls.ShellContent> object to a <xref:Microsoft.Maui.Controls.ContentPage> object.
|
||||
|
||||
## Bottom and top tabs
|
||||
|
||||
|
|
@ -166,11 +166,11 @@ This implicit conversion automatically wraps the third <xref:Microsoft.Maui.Cont
|
|||
|
||||
The <xref:Microsoft.Maui.Controls.Shell> class defines the following attached properties that control the appearance of tabs:
|
||||
|
||||
- `TabBarBackgroundColor`, of type `Color`, that defines the background color for the tab bar. If the property is unset, the `BackgroundColor` property value is used.
|
||||
- `TabBarDisabledColor`, of type `Color`, that defines the disabled color for the tab bar. If the property is unset, the `DisabledColor` property value is used.
|
||||
- `TabBarForegroundColor`, of type `Color`, that defines the foreground color for the tab bar. If the property is unset, the `ForegroundColor` property value is used.
|
||||
- `TabBarTitleColor`, of type `Color`, that defines the title color for the tab bar. If the property is unset, the `TitleColor` property value will be used.
|
||||
- `TabBarUnselectedColor`, of type `Color`, that defines the unselected color for the tab bar. If the property is unset, the `UnselectedColor` property value is used.
|
||||
- `TabBarBackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the background color for the tab bar. If the property is unset, the `BackgroundColor` property value is used.
|
||||
- `TabBarDisabledColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the disabled color for the tab bar. If the property is unset, the `DisabledColor` property value is used.
|
||||
- `TabBarForegroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the foreground color for the tab bar. If the property is unset, the `ForegroundColor` property value is used.
|
||||
- `TabBarTitleColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the title color for the tab bar. If the property is unset, the `TitleColor` property value will be used.
|
||||
- `TabBarUnselectedColor`, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the unselected color for the tab bar. If the property is unset, the `UnselectedColor` property value is used.
|
||||
|
||||
All of these properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings, and styled.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ ms.date: 04/05/2022
|
|||
|
||||
# Cell background color on iOS
|
||||
|
||||
This .NET Multi-platform App UI (.NET MAUI) iOS platform-specific sets the default background color of <xref:Microsoft.Maui.Controls.Cell> instances. It's consumed in XAML by setting the `Cell.DefaultBackgroundColor` bindable property to a `Color`:
|
||||
This .NET Multi-platform App UI (.NET MAUI) iOS platform-specific sets the default background color of <xref:Microsoft.Maui.Controls.Cell> instances. It's consumed in XAML by setting the `Cell.DefaultBackgroundColor` bindable property to a <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -40,8 +40,8 @@ ViewCell viewCell = new ViewCell { View = ... };
|
|||
viewCell.On<iOS>().SetDefaultBackgroundColor(Colors.Teal);
|
||||
```
|
||||
|
||||
The `ListView.On<iOS>` method specifies that this platform-specific will only run on iOS. The `Cell.SetDefaultBackgroundColor` method, in the `Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific` namespace, sets the cell background color to a specified `Color`. In addition, the `Cell.DefaultBackgroundColor` method can be used to retrieve the current cell background color.
|
||||
The `ListView.On<iOS>` method specifies that this platform-specific will only run on iOS. The `Cell.SetDefaultBackgroundColor` method, in the `Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific` namespace, sets the cell background color to a specified <xref:Microsoft.Maui.Graphics.Color>. In addition, the `Cell.DefaultBackgroundColor` method can be used to retrieve the current cell background color.
|
||||
|
||||
The result is that the background color in a <xref:Microsoft.Maui.Controls.Cell> can be set to a specific `Color`:
|
||||
The result is that the background color in a <xref:Microsoft.Maui.Controls.Cell> can be set to a specific <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
:::image type="content" source="media/cell-background-color/group-header-cell-color.png" alt-text="Screenshot of the Teal group header cells, on iOS.":::
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ ms.date: 04/05/2022
|
|||
|
||||
# Entry Cursor Color on iOS
|
||||
|
||||
This .NET Multi-platform App UI (.NET MAUI) iOS platform-specific sets the cursor color of an <xref:Microsoft.Maui.Controls.Entry> to a specified color. It's consumed in XAML by setting the `Entry.CursorColor` bindable property to a `Color`:
|
||||
This .NET Multi-platform App UI (.NET MAUI) iOS platform-specific sets the cursor color of an <xref:Microsoft.Maui.Controls.Entry> to a specified color. It's consumed in XAML by setting the `Entry.CursorColor` bindable property to a <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -28,8 +28,8 @@ Entry entry = new Microsoft.Maui.Controls.Entry();
|
|||
entry.On<iOS>().SetCursorColor(Colors.LimeGreen);
|
||||
```
|
||||
|
||||
The `Entry.On<iOS>` method specifies that this platform-specific will only run on iOS. The `Entry.SetCursorColor` method, in the `Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific` namespace, sets the cursor color to a specified `Color`. In addition, the `Entry.GetCursorColor` method can be used to retrieve the current cursor color.
|
||||
The `Entry.On<iOS>` method specifies that this platform-specific will only run on iOS. The `Entry.SetCursorColor` method, in the `Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific` namespace, sets the cursor color to a specified <xref:Microsoft.Maui.Graphics.Color>. In addition, the `Entry.GetCursorColor` method can be used to retrieve the current cursor color.
|
||||
|
||||
The result is that the cursor color in a <xref:Microsoft.Maui.Controls.Entry> can be set to a specific `Color`:
|
||||
The result is that the cursor color in a <xref:Microsoft.Maui.Controls.Entry> can be set to a specific <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
:::image type="content" source="media/entry-cursor-color/entry-cursorcolor.png" alt-text="Entry cursor color.":::
|
||||
|
|
|
|||
|
|
@ -83,9 +83,9 @@ Some APIs have changed in the move from Xamarin.Forms to .NET MAUI. This is mult
|
|||
|
||||
### Color changes
|
||||
|
||||
In Xamarin.Forms, the <xref:Xamarin.Forms.Color?displayProperty=fullName> struct lets you construct `Color` objects using `double` values, and provides named colors, such as <xref:Xamarin.Forms.Color.AliceBlue?displayProperty=fullName>. In .NET MAUI, this functionality has been separated into the <xref:Microsoft.Maui.Graphics.Color?displayProperty=fullName> class, and the <xref:Microsoft.Maui.Graphics.Colors?displayProperty=fullName> class.
|
||||
In Xamarin.Forms, the <xref:Xamarin.Forms.Color?displayProperty=fullName> struct lets you construct <xref:Microsoft.Maui.Graphics.Color> objects using `double` values, and provides named colors, such as <xref:Xamarin.Forms.Color.AliceBlue?displayProperty=fullName>. In .NET MAUI, this functionality has been separated into the <xref:Microsoft.Maui.Graphics.Color?displayProperty=fullName> class, and the <xref:Microsoft.Maui.Graphics.Colors?displayProperty=fullName> class.
|
||||
|
||||
The <xref:Microsoft.Maui.Graphics.Color?displayProperty=fullName> class, in the <xref:Microsoft.Maui.Graphics> namespace, lets you construct `Color` objects using `float` values, `byte` values, and `int` values. The <xref:Microsoft.Maui.Graphics.Colors?displayProperty=fullName> class, which is also in the <xref:Microsoft.Maui.Graphics> namespace, largely provides the same named colors.
|
||||
The <xref:Microsoft.Maui.Graphics.Color?displayProperty=fullName> class, in the <xref:Microsoft.Maui.Graphics> namespace, lets you construct <xref:Microsoft.Maui.Graphics.Color> objects using `float` values, `byte` values, and `int` values. The <xref:Microsoft.Maui.Graphics.Colors?displayProperty=fullName> class, which is also in the <xref:Microsoft.Maui.Graphics> namespace, largely provides the same named colors.
|
||||
|
||||
The following table shows the API changes between the <xref:Xamarin.Forms.Color?displayProperty=fullName> struct and the <xref:Microsoft.Maui.Graphics.Color?displayProperty=fullName> class:
|
||||
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ This section describes the platform-specific differences with the preferences AP
|
|||
<!-- markdownlint-disable MD025 -->
|
||||
# [Android](#tab/android)
|
||||
|
||||
All data is stored into [**Shared Preferences**](https://developer.android.com/training/data-storage/shared-preferences.html). If no `sharedName` is specified, the default **Shared Preferences** are used. Otherwise, the name is used to get a **private Shared Preferences** with the specified name.
|
||||
All data is stored into [Shared Preferences](https://developer.android.com/training/data-storage/shared-preferences.html). If no `sharedName` is specified, the default **Shared Preferences** are used. Otherwise, the name is used to get a **private Shared Preferences** with the specified name.
|
||||
|
||||
# [iOS/Mac Catalyst](#tab/macios)
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ All data is stored into [**Shared Preferences**](https://developer.android.com/t
|
|||
|
||||
## Persistence
|
||||
|
||||
Uninstalling the application causes all _preferences_ to be removed, except when the app runs on Android 6.0 (API level 23) or later, while using the [**Auto Backup**](https://developer.android.com/guide/topics/data/autobackup) feature. This feature is on by default and preserves app data, including **Shared Preferences**, which is what the **Preferences** API uses. You can disable this by following Google's [Auto Backup documentation](https://developer.android.com/guide/topics/data/autobackup).
|
||||
Uninstalling the application causes all _preferences_ to be removed, except when the app runs on Android 6.0 (API level 23) or later, while using the [Auto Backup](https://developer.android.com/guide/topics/data/autobackup) feature. This feature is on by default and preserves app data, including **Shared Preferences**, which is what the **Preferences** API uses. You can disable this by following Google's [Auto Backup documentation](https://developer.android.com/guide/topics/data/autobackup).
|
||||
|
||||
## Limitations
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ Because animations are uniquely identified by a combination of the animation own
|
|||
|
||||
## Create a custom animation
|
||||
|
||||
The examples shown here so far have demonstrated animations that could equally be achieved with the methods in the <xref:Microsoft.Maui.Controls.ViewExtensions> class. However, the advantage of the <xref:Microsoft.Maui.Controls.Animation> class is that it has access to the callback method, which is executed when the animated value changes. This allows the callback to implement any desired animation. For example, the following code example animates the <xref:Microsoft.Maui.Controls.VisualElement.BackgroundColor> property of a page by setting it to `Color` values created by the `Color.FromHsla` method, with hue values ranging from 0 to 1:
|
||||
The examples shown here so far have demonstrated animations that could equally be achieved with the methods in the <xref:Microsoft.Maui.Controls.ViewExtensions> class. However, the advantage of the <xref:Microsoft.Maui.Controls.Animation> class is that it has access to the callback method, which is executed when the animated value changes. This allows the callback to implement any desired animation. For example, the following code example animates the <xref:Microsoft.Maui.Controls.VisualElement.BackgroundColor> property of a page by setting it to <xref:Microsoft.Maui.Graphics.Color> values created by the `Color.FromHsla` method, with hue values ranging from 0 to 1:
|
||||
|
||||
```csharp
|
||||
new Animation (callback: v => BackgroundColor = Color.FromHsla (v, 1, 0.5),
|
||||
|
|
@ -113,9 +113,9 @@ The resulting animation provides the appearance of advancing the page background
|
|||
|
||||
## Create a custom animation extension method
|
||||
|
||||
The extension methods in the <xref:Microsoft.Maui.Controls.ViewExtensions> class animate a property from its current value to a specified value. This makes it difficult to create, for example, a `ColorTo` animation method that can be used to animate a color from one value to another. This is because different controls have different properties of type `Color`. While the <xref:Microsoft.Maui.Controls.VisualElement> class defines a <xref:Microsoft.Maui.Controls.VisualElement.BackgroundColor> property, this isn't always the desired `Color` property to animate.
|
||||
The extension methods in the <xref:Microsoft.Maui.Controls.ViewExtensions> class animate a property from its current value to a specified value. This makes it difficult to create, for example, a `ColorTo` animation method that can be used to animate a color from one value to another. This is because different controls have different properties of type <xref:Microsoft.Maui.Graphics.Color>. While the <xref:Microsoft.Maui.Controls.VisualElement> class defines a <xref:Microsoft.Maui.Controls.VisualElement.BackgroundColor> property, this isn't always the desired `Color` property to animate.
|
||||
|
||||
The solution to this problem is to not have the `ColorTo` method target a particular `Color` property. Instead, it can be written with a callback method that passes the interpolated `Color` value back to the caller. In addition, the method will take start and end `Color` arguments.
|
||||
The solution to this problem is to not have the `ColorTo` method target a particular `Color` property. Instead, it can be written with a callback method that passes the interpolated <xref:Microsoft.Maui.Graphics.Color> value back to the caller. In addition, the method will take start and end <xref:Microsoft.Maui.Graphics.Color> arguments.
|
||||
|
||||
The `ColorTo` method can be implemented as an extension method that uses the <xref:Microsoft.Maui.Controls.AnimationExtensions.Animate%2A> method in the <xref:Microsoft.Maui.Controls.AnimationExtensions> class to provide its functionality. This is because the <xref:Microsoft.Maui.Controls.AnimationExtensions.Animate%2A> method can be used to target properties that aren't of type `double`, as demonstrated in the following code example:
|
||||
|
||||
|
|
@ -148,7 +148,7 @@ public static class ViewExtensions
|
|||
}
|
||||
```
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.AnimationExtensions.Animate%2A> method requires a `transform` argument, which is a callback method. The input to this callback is always a `double` ranging from 0 to 1. Therefore, in this example the `ColorTo` method defines its own transform `Func` that accepts a `double` ranging from 0 to 1, and that returns a `Color` value corresponding to that value. The `Color` value is calculated by interpolating the `Red`, `Green`, `Blue`, and `Alpha` values of the two supplied `Color` arguments. The `Color` value is then passed to the callback method to be applied to a property. This approach allows the `ColorTo` method to animate any specified `Color` property:
|
||||
The <xref:Microsoft.Maui.Controls.AnimationExtensions.Animate%2A> method requires a `transform` argument, which is a callback method. The input to this callback is always a `double` ranging from 0 to 1. Therefore, in this example the `ColorTo` method defines its own transform `Func` that accepts a `double` ranging from 0 to 1, and that returns a <xref:Microsoft.Maui.Graphics.Color> value corresponding to that value. The <xref:Microsoft.Maui.Graphics.Color> value is calculated by interpolating the `Red`, `Green`, `Blue`, and `Alpha` values of the two supplied <xref:Microsoft.Maui.Graphics.Color> arguments. The <xref:Microsoft.Maui.Graphics.Color> value is then passed to the callback method to be applied to a property. This approach allows the `ColorTo` method to animate any specified <xref:Microsoft.Maui.Graphics.Color> property:
|
||||
|
||||
```csharp
|
||||
await Task.WhenAll(
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ Gradient stops are the building blocks of a gradient brush, and specify the colo
|
|||
|
||||
The <xref:Microsoft.Maui.Controls.GradientStop> class defines the following properties:
|
||||
|
||||
- `Color`, of type `Color`, which represents the color of the gradient stop.
|
||||
- `Color`, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the color of the gradient stop.
|
||||
- `Offset`, of type `float`, which represents the location of the gradient stop within the gradient vector. The default value of this property is 0, and valid values are in the range 0.0-1.0. The closer this value is to 0, the closer the color is to the start of the gradient. Similarly, the closer this value is to 1, the closer the color is to the end of the gradient.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -8,19 +8,19 @@ ms.date: 01/11/2022
|
|||
|
||||
[ Browse the sample](/samples/dotnet/maui-samples/userinterface-brushes)
|
||||
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.SolidColorBrush> class derives from the <xref:Microsoft.Maui.Controls.Brush> class, and is used to paint an area with a solid color. There are a variety of approaches to specifying the color of a <xref:Microsoft.Maui.Controls.SolidColorBrush>. For example, you can specify its color with a `Color` value or by using one of the predefined <xref:Microsoft.Maui.Controls.SolidColorBrush> objects provided by the <xref:Microsoft.Maui.Controls.Brush> class.
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.SolidColorBrush> class derives from the <xref:Microsoft.Maui.Controls.Brush> class, and is used to paint an area with a solid color. There are a variety of approaches to specifying the color of a <xref:Microsoft.Maui.Controls.SolidColorBrush>. For example, you can specify its color with a <xref:Microsoft.Maui.Graphics.Color> value or by using one of the predefined <xref:Microsoft.Maui.Controls.SolidColorBrush> objects provided by the <xref:Microsoft.Maui.Controls.Brush> class.
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.SolidColorBrush> class defines the `Color` property, of type `Color`, which represents the color of the brush. This property is backed by a <xref:Microsoft.Maui.Controls.BindableProperty> object, which means that it can be the target of data bindings, and styled.
|
||||
The <xref:Microsoft.Maui.Controls.SolidColorBrush> class defines the `Color` property, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the color of the brush. This property is backed by a <xref:Microsoft.Maui.Controls.BindableProperty> object, which means that it can be the target of data bindings, and styled.
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.SolidColorBrush> class also has an `IsEmpty` method that returns a `bool` that represents whether the brush has been assigned a color.
|
||||
|
||||
## Create a SolidColorBrush
|
||||
|
||||
There are three main techniques for creating a <xref:Microsoft.Maui.Controls.SolidColorBrush>. You can create a <xref:Microsoft.Maui.Controls.SolidColorBrush> from a `Color`, use a predefined brush, or create a <xref:Microsoft.Maui.Controls.SolidColorBrush> using hexadecimal notation.
|
||||
There are three main techniques for creating a <xref:Microsoft.Maui.Controls.SolidColorBrush>. You can create a <xref:Microsoft.Maui.Controls.SolidColorBrush> from a <xref:Microsoft.Maui.Graphics.Color>, use a predefined brush, or create a <xref:Microsoft.Maui.Controls.SolidColorBrush> using hexadecimal notation.
|
||||
|
||||
### Use a predefined Color
|
||||
|
||||
.NET MAUI includes a type converter that creates a <xref:Microsoft.Maui.Controls.SolidColorBrush> from a `Color` value. In XAML, this enables a <xref:Microsoft.Maui.Controls.SolidColorBrush> to be created from a predefined `Color` value:
|
||||
.NET MAUI includes a type converter that creates a <xref:Microsoft.Maui.Controls.SolidColorBrush> from a <xref:Microsoft.Maui.Graphics.Color> value. In XAML, this enables a <xref:Microsoft.Maui.Controls.SolidColorBrush> to be created from a predefined <xref:Microsoft.Maui.Graphics.Color> value:
|
||||
|
||||
```xaml
|
||||
<Frame Background="DarkBlue"
|
||||
|
|
@ -35,7 +35,7 @@ In this example, the background of the <xref:Microsoft.Maui.Controls.Frame> is p
|
|||
|
||||
:::image type="content" source="media/solidcolor/predefined-color.png" alt-text="Screenshot of a Frame painted with a predefined color.":::
|
||||
|
||||
Alternatively, the `Color` value can be specified using property tag syntax:
|
||||
Alternatively, the <xref:Microsoft.Maui.Graphics.Color> value can be specified using property tag syntax:
|
||||
|
||||
```xaml
|
||||
<Frame BorderColor="LightGray"
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ The appearance of an <xref:Microsoft.Maui.Controls.ActivityIndicator> is platfor
|
|||
|
||||
<xref:Microsoft.Maui.Controls.ActivityIndicator> defines the following properties:
|
||||
|
||||
- `Color` is a `Color` value that defines the color of the <xref:Microsoft.Maui.Controls.ActivityIndicator>.
|
||||
- `Color` is a <xref:Microsoft.Maui.Graphics.Color> value that defines the color of the <xref:Microsoft.Maui.Controls.ActivityIndicator>.
|
||||
- `IsRunning` is a `bool` value that indicates whether the <xref:Microsoft.Maui.Controls.ActivityIndicator> should be visible and animating, or hidden. The default value of this property is `false`, which indicates that the <xref:Microsoft.Maui.Controls.ActivityIndicator> isn't visible.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.BoxView
|
|||
|
||||
<xref:Microsoft.Maui.Controls.BoxView> defines the following properties:
|
||||
|
||||
- `Color`, of type `Color`, which defines the color of the <xref:Microsoft.Maui.Controls.BoxView>.
|
||||
- `Color`, of type <xref:Microsoft.Maui.Graphics.Color>, which defines the color of the <xref:Microsoft.Maui.Controls.BoxView>.
|
||||
- `CornerRadius`, of type `CornerRadius`, which defines the corner radius of the <xref:Microsoft.Maui.Controls.BoxView>. This property can be set to a single `double` uniform corner radius value, or a `CornerRadius` structure defined by four `double` values that are applied to the top left, top right, bottom left, and bottom right of the <xref:Microsoft.Maui.Controls.BoxView>.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Button>
|
|||
|
||||
<xref:Microsoft.Maui.Controls.Button> defines the following properties:
|
||||
|
||||
- `BorderColor`, of type `Color`, describes the border color of the button.
|
||||
- `BorderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, describes the border color of the button.
|
||||
- `BorderWidth`, of type `double`, defines the width of the button's border.
|
||||
- `CharacterSpacing`, of type `double`, defines the spacing between characters of the button's text.
|
||||
- `Command`, of type `ICommand`, defines the command that's executed when the button is tapped.
|
||||
|
|
@ -25,7 +25,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Button>
|
|||
- `LineBreakMode`, of type `LineBreakMode`, determines how text should be handled when it can't fit on one line.
|
||||
- `Padding`, of type `Thickness`, determines the button's padding.
|
||||
- `Text`, of type `string`, defines the text displayed as the content of the button.
|
||||
- `TextColor`, of type `Color`, describes the color of the button's text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, describes the color of the button's text.
|
||||
- `TextTransform`, of type `TextTransform`, defines the casing of the button's text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ ms.date: 01/18/2022
|
|||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CarouselView> defines the following properties that can be used to provide user feedback when there's no data to display:
|
||||
|
||||
- `EmptyView`, of type `object`, the string, binding, or view that will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The default value is `null`.
|
||||
- `EmptyViewTemplate`, of type `DataTemplate`, the template to use to format the specified `EmptyView`. The default value is `null`.
|
||||
- `EmptyViewTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, the template to use to format the specified `EmptyView`. The default value is `null`.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -102,7 +102,7 @@ When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`,
|
|||
|
||||
## Display a templated custom type when data is unavailable
|
||||
|
||||
The `EmptyView` property can be set to a custom type, whose template is displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The `EmptyViewTemplate` property can be set to a `DataTemplate` that defines the appearance of the `EmptyView`. The following XAML shows an example of this scenario:
|
||||
The `EmptyView` property can be set to a custom type, whose template is displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The `EmptyViewTemplate` property can be set to a <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of the `EmptyView`. The following XAML shows an example of this scenario:
|
||||
|
||||
```xaml
|
||||
<StackLayout Margin="20">
|
||||
|
|
@ -160,7 +160,7 @@ public class FilterData : BindableObject
|
|||
}
|
||||
```
|
||||
|
||||
The `EmptyView` property is set to a `FilterData` object, and the `Filter` property data binds to the `SearchBar.Text` property. When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CarouselView> is filtered for the search term stored in the `Filter` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.Label> defined in the `DataTemplate`, that's set as the `EmptyViewTemplate` property value, is displayed.
|
||||
The `EmptyView` property is set to a `FilterData` object, and the `Filter` property data binds to the `SearchBar.Text` property. When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CarouselView> is filtered for the search term stored in the `Filter` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.Label> defined in the <xref:Microsoft.Maui.Controls.DataTemplate>, that's set as the `EmptyViewTemplate` property value, is displayed.
|
||||
|
||||
> [!NOTE]
|
||||
> When displaying a templated custom type when data is unavailable, the `EmptyViewTemplate` property can be set to a view that contains multiple child views.
|
||||
|
|
@ -238,7 +238,7 @@ For more information about resource dictionaries, see [Resource dictionaries](~/
|
|||
|
||||
## Choose an EmptyViewTemplate at runtime
|
||||
|
||||
The appearance of the `EmptyView` can be chosen at runtime, based on its value, by setting the `CarouselView.EmptyViewTemplate` property to a `DataTemplateSelector` object:
|
||||
The appearance of the `EmptyView` can be chosen at runtime, based on its value, by setting the `CarouselView.EmptyViewTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector> object:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -287,7 +287,7 @@ carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
|
|||
|
||||
The `EmptyView` property is set to the `SearchBar.Text` property, and the `EmptyViewTemplate` property is set to a `SearchTermDataTemplateSelector` object.
|
||||
|
||||
When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CarouselView> is filtered for the search term stored in the `SearchBar.Text` property. If the filtering operation yields no data, the `DataTemplate` chosen by the `SearchTermDataTemplateSelector` object is set as the `EmptyViewTemplate` property and displayed.
|
||||
When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CarouselView> is filtered for the search term stored in the `SearchBar.Text` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.DataTemplate> chosen by the `SearchTermDataTemplateSelector` object is set as the `EmptyViewTemplate` property and displayed.
|
||||
|
||||
The following example shows the `SearchTermDataTemplateSelector` class:
|
||||
|
||||
|
|
@ -305,6 +305,6 @@ public class SearchTermDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `SearchTermTemplateSelector` class defines `DefaultTemplate` and `OtherTemplate` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` override returns `DefaultTemplate`, which displays a message to the user, when the search query isn't equal to "xamarin". When the search query is equal to "xamarin", the `OnSelectTemplate` override returns `OtherTemplate`, which displays a basic message to the user.
|
||||
The `SearchTermTemplateSelector` class defines `DefaultTemplate` and `OtherTemplate` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` override returns `DefaultTemplate`, which displays a message to the user, when the search query isn't equal to "xamarin". When the search query is equal to "xamarin", the `OnSelectTemplate` override returns `OtherTemplate`, which displays a basic message to the user.
|
||||
|
||||
For more information about data template selectors, see [Create a DataTemplateSelector](~/fundamentals/datatemplate.md#create-a-datatemplateselector).
|
||||
|
|
|
|||
|
|
@ -328,7 +328,7 @@ The following XAML example shows how to define the `CurrentItem`, `PreviousItem`
|
|||
In this example, the `CurrentItem` visual state specifies that the current item displayed by the <xref:Microsoft.Maui.Controls.CarouselView> will have its `Scale` property changed from its default value of 1 to 1.1. The `PreviousItem` and `NextItem` visual states specify that the items surrounding the current item will be displayed with an `Opacity` value of 0.5. The `DefaultItem` visual state specifies that the remainder of the items displayed by the <xref:Microsoft.Maui.Controls.CarouselView> will be displayed with an `Opacity` value of 0.25.
|
||||
|
||||
> [!NOTE]
|
||||
> Alternatively, the visual states can be defined in a <xref:Microsoft.Maui.Controls.Style> that has a `TargetType` property value that's the type of the root element of the `DataTemplate`, which is set as the `ItemTemplate` property value.
|
||||
> Alternatively, the visual states can be defined in a <xref:Microsoft.Maui.Controls.Style> that has a `TargetType` property value that's the type of the root element of the <xref:Microsoft.Maui.Controls.DataTemplate>, which is set as the `ItemTemplate` property value.
|
||||
|
||||
The following screenshot shows the `CurrentItem`, `PreviousItem`, and `NextItem` visual states:
|
||||
|
||||
|
|
|
|||
|
|
@ -216,7 +216,7 @@ This code results in a vertical layout that has a spacing of 20 between items.
|
|||
|
||||
## Dynamic resizing of items
|
||||
|
||||
Items in a <xref:Microsoft.Maui.Controls.CarouselView> can be dynamically resized at runtime by changing layout related properties of elements within the `DataTemplate`. For example, the following code example changes the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties of an <xref:Microsoft.Maui.Controls.Image> object, and the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> property of its parent <xref:Microsoft.Maui.Controls.Frame>:
|
||||
Items in a <xref:Microsoft.Maui.Controls.CarouselView> can be dynamically resized at runtime by changing layout related properties of elements within the <xref:Microsoft.Maui.Controls.DataTemplate>. For example, the following code example changes the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties of an <xref:Microsoft.Maui.Controls.Image> object, and the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> property of its parent <xref:Microsoft.Maui.Controls.Frame>:
|
||||
|
||||
```csharp
|
||||
void OnImageTapped(object sender, EventArgs e)
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ ms.date: 01/18/2022
|
|||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CarouselView> includes the following properties that define the data to be displayed, and its appearance:
|
||||
|
||||
- `ItemsSource`, of type `IEnumerable`, specifies the collection of items to be displayed, and has a default value of `null`.
|
||||
- `ItemTemplate`, of type `DataTemplate`, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
- `ItemTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -48,7 +48,7 @@ For information on how to change the <xref:Microsoft.Maui.Controls.CarouselView>
|
|||
|
||||
## Define item appearance
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView> can be defined by setting the `CarouselView.ItemTemplate` property to a `DataTemplate`:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView> can be defined by setting the `CarouselView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CarouselView ItemsSource="{Binding Monkeys}">
|
||||
|
|
@ -122,7 +122,7 @@ carouselView.ItemTemplate = new DataTemplate(() =>
|
|||
});
|
||||
```
|
||||
|
||||
The elements specified in the `DataTemplate` define the appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView>. In the example, layout within the `DataTemplate` is managed by a <xref:Microsoft.Maui.Controls.StackLayout>, and the data is displayed with an <xref:Microsoft.Maui.Controls.Image> object, and three <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
The elements specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView>. In the example, layout within the <xref:Microsoft.Maui.Controls.DataTemplate> is managed by a <xref:Microsoft.Maui.Controls.StackLayout>, and the data is displayed with an <xref:Microsoft.Maui.Controls.Image> object, and three <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
|
||||
```csharp
|
||||
public class Monkey
|
||||
|
|
@ -142,7 +142,7 @@ For more information about data templates, see [Data templates](~/fundamentals/d
|
|||
|
||||
## Choose item appearance at runtime
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView> can be chosen at runtime, based on the item value, by setting the `CarouselView.ItemTemplate` property to a `DataTemplateSelector` object:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CarouselView> can be chosen at runtime, based on the item value, by setting the `CarouselView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector> object:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -192,14 +192,14 @@ public class MonkeyDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays its data grayed out:
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays its data grayed out:
|
||||
|
||||
:::image type="content" source="media/populate-data/datatemplateselector.png" alt-text="Screenshot of a CarouselView runtime item template selection.":::
|
||||
|
||||
For more information about data template selectors, see [Create a DataTemplateSelector](~/fundamentals/datatemplate.md#create-a-datatemplateselector).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> When using <xref:Microsoft.Maui.Controls.CarouselView>, never set the root element of your `DataTemplate` objects to a <xref:Microsoft.Maui.Controls.ViewCell>. This will result in an exception being thrown because <xref:Microsoft.Maui.Controls.CarouselView> has no concept of cells.
|
||||
> When using <xref:Microsoft.Maui.Controls.CarouselView>, never set the root element of your <xref:Microsoft.Maui.Controls.DataTemplate> objects to a <xref:Microsoft.Maui.Controls.ViewCell>. This will result in an exception being thrown because <xref:Microsoft.Maui.Controls.CarouselView> has no concept of cells.
|
||||
|
||||
## Display indicators
|
||||
|
||||
|
|
@ -231,7 +231,7 @@ For more information about indicators, see [IndicatorView](~/user-interface/cont
|
|||
|
||||
## Context menus
|
||||
|
||||
<xref:Microsoft.Maui.Controls.CarouselView> supports context menus for items of data through the <xref:Microsoft.Maui.Controls.SwipeView>, which reveals the context menu with a swipe gesture. The <xref:Microsoft.Maui.Controls.SwipeView> is a container control that wraps around an item of content, and provides context menu items for that item of content. Therefore, context menus are implemented for a <xref:Microsoft.Maui.Controls.CarouselView> by creating a <xref:Microsoft.Maui.Controls.SwipeView> that defines the content that the <xref:Microsoft.Maui.Controls.SwipeView> wraps around, and the context menu items that are revealed by the swipe gesture. This is achieved by adding a <xref:Microsoft.Maui.Controls.SwipeView> to the `DataTemplate` that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CarouselView>:
|
||||
<xref:Microsoft.Maui.Controls.CarouselView> supports context menus for items of data through the <xref:Microsoft.Maui.Controls.SwipeView>, which reveals the context menu with a swipe gesture. The <xref:Microsoft.Maui.Controls.SwipeView> is a container control that wraps around an item of content, and provides context menu items for that item of content. Therefore, context menus are implemented for a <xref:Microsoft.Maui.Controls.CarouselView> by creating a <xref:Microsoft.Maui.Controls.SwipeView> that defines the content that the <xref:Microsoft.Maui.Controls.SwipeView> wraps around, and the context menu items that are revealed by the swipe gesture. This is achieved by adding a <xref:Microsoft.Maui.Controls.SwipeView> to the <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CarouselView>:
|
||||
|
||||
```xaml
|
||||
<CarouselView x:Name="carouselView"
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CheckBo
|
|||
<xref:Microsoft.Maui.Controls.CheckBox> defines the following properties:
|
||||
|
||||
- `IsChecked`, of type `bool`, which indicates whether the <xref:Microsoft.Maui.Controls.CheckBox> is checked. This property has a default binding mode of `TwoWay`.
|
||||
- `Color`, of type `Color`, which indicates the color of the <xref:Microsoft.Maui.Controls.CheckBox>.
|
||||
- `Color`, of type <xref:Microsoft.Maui.Graphics.Color>, which indicates the color of the <xref:Microsoft.Maui.Controls.CheckBox>.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be styled, and be the target of data bindings.
|
||||
|
||||
|
|
@ -110,13 +110,13 @@ Sometimes an application enters a state where a <xref:Microsoft.Maui.Controls.Ch
|
|||
|
||||
## CheckBox appearance
|
||||
|
||||
In addition to the properties that <xref:Microsoft.Maui.Controls.CheckBox> inherits from the <xref:Microsoft.Maui.Controls.View> class, <xref:Microsoft.Maui.Controls.CheckBox> also defines a `Color` property that sets its color to a `Color`:
|
||||
In addition to the properties that <xref:Microsoft.Maui.Controls.CheckBox> inherits from the <xref:Microsoft.Maui.Controls.View> class, <xref:Microsoft.Maui.Controls.CheckBox> also defines a `Color` property that sets its color to a <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
```xaml
|
||||
<CheckBox Color="Red" />
|
||||
```
|
||||
|
||||
The following screenshot shows a series of checked <xref:Microsoft.Maui.Controls.CheckBox> objects, where each object has its `Color` property set to a different `Color`:
|
||||
The following screenshot shows a series of checked <xref:Microsoft.Maui.Controls.CheckBox> objects, where each object has its `Color` property set to a different <xref:Microsoft.Maui.Graphics.Color>:
|
||||
|
||||
:::image type="content" source="media/checkbox/checkbox-colors.png" alt-text="Screenshot of colored CheckBoxes.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ ms.date: 01/18/2022
|
|||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CollectionView> defines the following properties that can be used to provide user feedback when there's no data to display:
|
||||
|
||||
- `EmptyView`, of type `object`, the string, binding, or view that will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The default value is `null`.
|
||||
- `EmptyViewTemplate`, of type `DataTemplate`, the template to use to format the specified `EmptyView`. The default value is `null`.
|
||||
- `EmptyViewTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, the template to use to format the specified `EmptyView`. The default value is `null`.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -109,7 +109,7 @@ When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`,
|
|||
|
||||
## Display a templated custom type when data is unavailable
|
||||
|
||||
The `EmptyView` property can be set to a custom type, whose template is displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The `EmptyViewTemplate` property can be set to a `DataTemplate` that defines the appearance of the `EmptyView`. The following XAML shows an example of this scenario:
|
||||
The `EmptyView` property can be set to a custom type, whose template is displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The `EmptyViewTemplate` property can be set to a <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of the `EmptyView`. The following XAML shows an example of this scenario:
|
||||
|
||||
```xaml
|
||||
<StackLayout Margin="20">
|
||||
|
|
@ -169,7 +169,7 @@ public class FilterData : BindableObject
|
|||
}
|
||||
```
|
||||
|
||||
The `EmptyView` property is set to a `FilterData` object, and the `Filter` property data binds to the `SearchBar.Text` property. When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CollectionView> is filtered for the search term stored in the `Filter` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.Label> defined in the `DataTemplate`, that's set as the `EmptyViewTemplate` property value, is displayed:
|
||||
The `EmptyView` property is set to a `FilterData` object, and the `Filter` property data binds to the `SearchBar.Text` property. When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CollectionView> is filtered for the search term stored in the `Filter` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.Label> defined in the <xref:Microsoft.Maui.Controls.DataTemplate>, that's set as the `EmptyViewTemplate` property value, is displayed:
|
||||
|
||||
:::image type="content" source="media/emptyview/emptyviewtemplate.png" alt-text="Screenshot of a CollectionView vertical list with an empty view template.":::
|
||||
|
||||
|
|
@ -251,7 +251,7 @@ For more information about resource dictionaries, see [Resource dictionaries](~/
|
|||
|
||||
## Choose an EmptyViewTemplate at runtime
|
||||
|
||||
The appearance of the `EmptyView` can be chosen at runtime, based on its value, by setting the `CollectionView.EmptyViewTemplate` property to a `DataTemplateSelector` object:
|
||||
The appearance of the `EmptyView` can be chosen at runtime, based on its value, by setting the `CollectionView.EmptyViewTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector> object:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -296,7 +296,7 @@ collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
|
|||
|
||||
The `EmptyView` property is set to the `SearchBar.Text` property, and the `EmptyViewTemplate` property is set to a `SearchTermDataTemplateSelector` object.
|
||||
|
||||
When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CollectionView> is filtered for the search term stored in the `SearchBar.Text` property. If the filtering operation yields no data, the `DataTemplate` chosen by the `SearchTermDataTemplateSelector` object is set as the `EmptyViewTemplate` property and displayed.
|
||||
When the <xref:Microsoft.Maui.Controls.SearchBar> executes the `FilterCommand`, the collection displayed by the <xref:Microsoft.Maui.Controls.CollectionView> is filtered for the search term stored in the `SearchBar.Text` property. If the filtering operation yields no data, the <xref:Microsoft.Maui.Controls.DataTemplate> chosen by the `SearchTermDataTemplateSelector` object is set as the `EmptyViewTemplate` property and displayed.
|
||||
|
||||
The following example shows the `SearchTermDataTemplateSelector` class:
|
||||
|
||||
|
|
@ -314,7 +314,7 @@ public class SearchTermDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `SearchTermTemplateSelector` class defines `DefaultTemplate` and `OtherTemplate` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` override returns `DefaultTemplate`, which displays a message to the user, when the search query isn't equal to "xamarin". When the search query is equal to "xamarin", the `OnSelectTemplate` override returns `OtherTemplate`, which displays a basic message to the user:
|
||||
The `SearchTermTemplateSelector` class defines `DefaultTemplate` and `OtherTemplate` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` override returns `DefaultTemplate`, which displays a message to the user, when the search query isn't equal to "xamarin". When the search query is equal to "xamarin", the `OnSelectTemplate` override returns `OtherTemplate`, which displays a basic message to the user:
|
||||
|
||||
:::image type="content" source="media/emptyview/datatemplateselector.png" alt-text="Screenshot of a CollectionView runtime empty view template selection.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ Large data sets can often become unwieldy when presented in a continually scroll
|
|||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CollectionView> supports displaying grouped data, and defines the following properties that control how it will be presented:
|
||||
|
||||
- `IsGrouped`, of type `bool`, indicates whether the underlying data should be displayed in groups. The default value of this property is `false`.
|
||||
- `GroupHeaderTemplate`, of type `DataTemplate`, the template to use for the header of each group.
|
||||
- `GroupFooterTemplate`, of type `DataTemplate`, the template to use for the footer of each group.
|
||||
- `GroupHeaderTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, the template to use for the header of each group.
|
||||
- `GroupFooterTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, the template to use for the footer of each group.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -168,14 +168,14 @@ collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");
|
|||
// ...
|
||||
```
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> is defined by setting the `CollectionView.ItemTemplate` property to a `DataTemplate`. For more information, see [Define item appearance](~/user-interface/controls/collectionview/populate-data.md#define-item-appearance).
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> is defined by setting the `CollectionView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>. For more information, see [Define item appearance](~/user-interface/controls/collectionview/populate-data.md#define-item-appearance).
|
||||
|
||||
> [!NOTE]
|
||||
> By default, <xref:Microsoft.Maui.Controls.CollectionView> will display the group name in the group header and footer. This behavior can be changed by customizing the group header and group footer.
|
||||
|
||||
## Customize the group header
|
||||
|
||||
The appearance of each group header can be customized by setting the `CollectionView.GroupHeaderTemplate` property to a `DataTemplate`:
|
||||
The appearance of each group header can be customized by setting the `CollectionView.GroupHeaderTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CollectionView ItemsSource="{Binding Animals}"
|
||||
|
|
@ -198,7 +198,7 @@ In this example, each group header is set to a <xref:Microsoft.Maui.Controls.Lab
|
|||
|
||||
## Customize the group footer
|
||||
|
||||
The appearance of each group footer can be customized by setting the `CollectionView.GroupFooterTemplate` property to a `DataTemplate`:
|
||||
The appearance of each group footer can be customized by setting the `CollectionView.GroupFooterTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CollectionView ItemsSource="{Binding Animals}"
|
||||
|
|
@ -228,7 +228,7 @@ When a <xref:Microsoft.Maui.Controls.CollectionView> displays grouped data, it w
|
|||
|
||||
## Group without templates
|
||||
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> can display correctly grouped data without setting the `CollectionView.ItemTemplate` property to a `DataTemplate`:
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> can display correctly grouped data without setting the `CollectionView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CollectionView ItemsSource="{Binding Animals}"
|
||||
|
|
|
|||
|
|
@ -35,14 +35,14 @@ While the <xref:Microsoft.Maui.Controls.CollectionView> and <xref:Microsoft.Maui
|
|||
| Concept | ListView API | CollectionView |
|
||||
|---|---|---|
|
||||
| Data | `ItemsSource` | A <xref:Microsoft.Maui.Controls.CollectionView> is populated with data by setting its `ItemsSource` property. For more information, see [Populate a CollectionView with data](populate-data.md#populate-a-collectionview-with-data). |
|
||||
| Item appearance | `ItemTemplate` | The appearance of each item in a <xref:Microsoft.Maui.Controls.CollectionView> can be defined by setting the `ItemTemplate` property to a `DataTemplate`. For more information, see [Define item appearance](populate-data.md#define-item-appearance). |
|
||||
| Item appearance | `ItemTemplate` | The appearance of each item in a <xref:Microsoft.Maui.Controls.CollectionView> can be defined by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>. For more information, see [Define item appearance](populate-data.md#define-item-appearance). |
|
||||
| Cells | <xref:Microsoft.Maui.Controls.TextCell>, <xref:Microsoft.Maui.Controls.ImageCell>, <xref:Microsoft.Maui.Controls.ViewCell> | <xref:Microsoft.Maui.Controls.CollectionView> has no concept of cells, and therefore no concept of disclosure indicators. Instead, a data template is used to define the appearance of each item of data in the list. |
|
||||
| Row separators | `SeparatorColor`, `SeparatorVisibility` | <xref:Microsoft.Maui.Controls.CollectionView> does not include built-in separators. These can be provided, if desired, in the item template. |
|
||||
| Selection | `SelectionMode`, `SelectedItem` | <xref:Microsoft.Maui.Controls.CollectionView> supports single and multiple selection. For more information, see [Configure CollectionView item selection](selection.md). |
|
||||
| Row height | `HasUnevenRows`, `RowHeight` | In a <xref:Microsoft.Maui.Controls.CollectionView>, the row height of each item is determined by the `ItemSizingStrategy` property. For more information, see [Item sizing](layout.md#item-sizing).|
|
||||
| Caching | `CachingStrategy` | <xref:Microsoft.Maui.Controls.CollectionView> automatically uses the virtualization provided by the underlying native controls. |
|
||||
| Headers and footers | `Header`, `HeaderElement`, `HeaderTemplate`, `Footer`, `FooterElement`, `FooterTemplate` | <xref:Microsoft.Maui.Controls.CollectionView> can present a header and footer that scroll with the items in the list, via the `Header`, `Footer`, `HeaderTemplate`, and `FooterTemplate` properties. For more information, see [Headers and footers](layout.md#headers-and-footers). |
|
||||
| Grouping | `GroupDisplayBinding`, `GroupHeaderTemplate`, `GroupShortNameBinding`, `IsGroupingEnabled` | <xref:Microsoft.Maui.Controls.CollectionView> displays correctly grouped data by setting its `IsGrouped` property to `true`. Group headers and group footers can be customized by setting the `GroupHeaderTemplate` and `GroupFooterTemplate` properties to `DataTemplate` objects. For more information, see [Display grouped data in a CollectionView](grouping.md). |
|
||||
| Grouping | `GroupDisplayBinding`, `GroupHeaderTemplate`, `GroupShortNameBinding`, `IsGroupingEnabled` | <xref:Microsoft.Maui.Controls.CollectionView> displays correctly grouped data by setting its `IsGrouped` property to `true`. Group headers and group footers can be customized by setting the `GroupHeaderTemplate` and `GroupFooterTemplate` properties to <xref:Microsoft.Maui.Controls.DataTemplate> objects. For more information, see [Display grouped data in a CollectionView](grouping.md). |
|
||||
| Pull to refresh | `IsPullToRefreshEnabled`, `IsRefreshing`, `RefreshAllowed`, `RefreshCommand`, `RefreshControlColor`, `BeginRefresh()`, `EndRefresh()` | Pull to refresh functionality is supported by setting a <xref:Microsoft.Maui.Controls.CollectionView> as the child of a <xref:Microsoft.Maui.Controls.RefreshView>. For more information, see [Pull to refresh](populate-data.md#pull-to-refresh). |
|
||||
| Context menu items | `ContextActions` | Context menu items are supported by setting a <xref:Microsoft.Maui.Controls.SwipeView> as the root view in the `DataTemplate` that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CollectionView>. For more information, see [Context menus](populate-data.md#context-menus). |
|
||||
| Context menu items | `ContextActions` | Context menu items are supported by setting a <xref:Microsoft.Maui.Controls.SwipeView> as the root view in the <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CollectionView>. For more information, see [Context menus](populate-data.md#context-menus). |
|
||||
| Scrolling | `ScrollTo()` | <xref:Microsoft.Maui.Controls.CollectionView> defines `ScrollTo` methods, which scroll items into view. For more information, see [Control scrolling in a CollectionView](scrolling.md). |
|
||||
|
|
|
|||
|
|
@ -314,14 +314,14 @@ By default, a horizontal `GridItemsLayout` will display items in a single row. H
|
|||
|
||||
## Headers and footers
|
||||
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> can present a header and footer that scroll with the items in the list. The header and footer can be strings, views, or `DataTemplate` objects.
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> can present a header and footer that scroll with the items in the list. The header and footer can be strings, views, or <xref:Microsoft.Maui.Controls.DataTemplate> objects.
|
||||
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> defines the following properties for specifying the header and footer:
|
||||
|
||||
- `Header`, of type `object`, specifies the string, binding, or view that will be displayed at the start of the list.
|
||||
- `HeaderTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Header`.
|
||||
- `HeaderTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Header`.
|
||||
- `Footer`, of type `object`, specifies the string, binding, or view that will be displayed at the end of the list.
|
||||
- `FooterTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Footer`.
|
||||
- `FooterTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Footer`.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -402,7 +402,7 @@ This code results in the following screenshots, with the header shown in the iOS
|
|||
|
||||
### Display a templated header and footer
|
||||
|
||||
The `HeaderTemplate` and `FooterTemplate` properties can be set to `DataTemplate` objects that are used to format the header and footer. In this scenario, the `Header` and `Footer` properties must bind to the current source for the templates to be applied, as shown in the following example:
|
||||
The `HeaderTemplate` and `FooterTemplate` properties can be set to <xref:Microsoft.Maui.Controls.DataTemplate> objects that are used to format the header and footer. In this scenario, the `Header` and `Footer` properties must bind to the current source for the templates to be applied, as shown in the following example:
|
||||
|
||||
```xaml
|
||||
<CollectionView ItemsSource="{Binding Monkeys}"
|
||||
|
|
@ -528,7 +528,7 @@ This code results in a vertical two-column grid that has a vertical spacing of 2
|
|||
|
||||
## Item sizing
|
||||
|
||||
By default, each item in a <xref:Microsoft.Maui.Controls.CollectionView> is individually measured and sized, provided that the UI elements in the `DataTemplate` don't specify fixed sizes. This behavior, which can be changed, is specified by the `CollectionView.ItemSizingStrategy` property value. This property value can be set to one of the `ItemSizingStrategy` enumeration members:
|
||||
By default, each item in a <xref:Microsoft.Maui.Controls.CollectionView> is individually measured and sized, provided that the UI elements in the <xref:Microsoft.Maui.Controls.DataTemplate> don't specify fixed sizes. This behavior, which can be changed, is specified by the `CollectionView.ItemSizingStrategy` property value. This property value can be set to one of the `ItemSizingStrategy` enumeration members:
|
||||
|
||||
- `MeasureAllItems` – each item is individually measured. This is the default value.
|
||||
- `MeasureFirstItem` – only the first item is measured, with all subsequent items being given the same size as the first item.
|
||||
|
|
@ -557,7 +557,7 @@ CollectionView collectionView = new CollectionView
|
|||
|
||||
## Dynamic resizing of items
|
||||
|
||||
Items in a <xref:Microsoft.Maui.Controls.CollectionView> can be dynamically resized at runtime by changing layout related properties of elements within the `DataTemplate`. For example, the following code example changes the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties of an <xref:Microsoft.Maui.Controls.Image> object:
|
||||
Items in a <xref:Microsoft.Maui.Controls.CollectionView> can be dynamically resized at runtime by changing layout related properties of elements within the <xref:Microsoft.Maui.Controls.DataTemplate>. For example, the following code example changes the <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> and <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest> properties of an <xref:Microsoft.Maui.Controls.Image> object:
|
||||
|
||||
```csharp
|
||||
void OnImageTapped(object sender, EventArgs e)
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ ms.date: 01/18/2022
|
|||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.CollectionView> includes the following properties that define the data to be displayed, and its appearance:
|
||||
|
||||
- `ItemsSource`, of type `IEnumerable`, specifies the collection of items to be displayed, and has a default value of `null`.
|
||||
- `ItemTemplate`, of type `DataTemplate`, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
- `ItemTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ For information on how to change the <xref:Microsoft.Maui.Controls.CollectionVie
|
|||
|
||||
## Define item appearance
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> can be defined by setting the `CollectionView.ItemTemplate` property to a `DataTemplate`:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> can be defined by setting the `CollectionView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<CollectionView ItemsSource="{Binding Monkeys}">
|
||||
|
|
@ -119,7 +119,7 @@ collectionView.ItemTemplate = new DataTemplate(() =>
|
|||
});
|
||||
```
|
||||
|
||||
The elements specified in the `DataTemplate` define the appearance of each item in the list. In the example, layout within the `DataTemplate` is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and two <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
The elements specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each item in the list. In the example, layout within the <xref:Microsoft.Maui.Controls.DataTemplate> is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and two <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
|
||||
```csharp
|
||||
public class Monkey
|
||||
|
|
@ -139,7 +139,7 @@ For more information about data templates, see [Data templates](~/fundamentals/d
|
|||
|
||||
## Choose item appearance at runtime
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> can be chosen at runtime, based on the item value, by setting the `CollectionView.ItemTemplate` property to a `DataTemplateSelector` object:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.CollectionView> can be chosen at runtime, based on the item value, by setting the `CollectionView.ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector> object:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -188,18 +188,18 @@ public class MonkeyDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template, which displays the monkey name and location in teal, when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays the monkey name and location in silver:
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template, which displays the monkey name and location in teal, when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays the monkey name and location in silver:
|
||||
|
||||
:::image type="content" source="media/populate-data/datatemplateselector.png" alt-text="Screenshot of CollectionView runtime item template selection.":::
|
||||
|
||||
For more information about data template selectors, see [Create a DataTemplateSelector](~/fundamentals/datatemplate.md#create-a-datatemplateselector).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> When using <xref:Microsoft.Maui.Controls.CollectionView>, never set the root element of your `DataTemplate` objects to a <xref:Microsoft.Maui.Controls.ViewCell>. This will result in an exception being thrown because <xref:Microsoft.Maui.Controls.CollectionView> has no concept of cells.
|
||||
> When using <xref:Microsoft.Maui.Controls.CollectionView>, never set the root element of your <xref:Microsoft.Maui.Controls.DataTemplate> objects to a <xref:Microsoft.Maui.Controls.ViewCell>. This will result in an exception being thrown because <xref:Microsoft.Maui.Controls.CollectionView> has no concept of cells.
|
||||
|
||||
## Context menus
|
||||
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> supports context menus for items of data through the <xref:Microsoft.Maui.Controls.SwipeView>, which reveals the context menu with a swipe gesture. The <xref:Microsoft.Maui.Controls.SwipeView> is a container control that wraps around an item of content, and provides context menu items for that item of content. Therefore, context menus are implemented for a <xref:Microsoft.Maui.Controls.CollectionView> by creating a <xref:Microsoft.Maui.Controls.SwipeView> that defines the content that the <xref:Microsoft.Maui.Controls.SwipeView> wraps around, and the context menu items that are revealed by the swipe gesture. This is achieved by setting the <xref:Microsoft.Maui.Controls.SwipeView> as the root view in the `DataTemplate` that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CollectionView>:
|
||||
<xref:Microsoft.Maui.Controls.CollectionView> supports context menus for items of data through the <xref:Microsoft.Maui.Controls.SwipeView>, which reveals the context menu with a swipe gesture. The <xref:Microsoft.Maui.Controls.SwipeView> is a container control that wraps around an item of content, and provides context menu items for that item of content. Therefore, context menus are implemented for a <xref:Microsoft.Maui.Controls.CollectionView> by creating a <xref:Microsoft.Maui.Controls.SwipeView> that defines the content that the <xref:Microsoft.Maui.Controls.SwipeView> wraps around, and the context menu items that are revealed by the swipe gesture. This is achieved by setting the <xref:Microsoft.Maui.Controls.SwipeView> as the root view in the <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each item of data in the <xref:Microsoft.Maui.Controls.CollectionView>:
|
||||
|
||||
```xaml
|
||||
<CollectionView x:Name="collectionView"
|
||||
|
|
|
|||
|
|
@ -291,7 +291,7 @@ The `SelectedItem` and `SelectedItems` properties can be cleared by setting them
|
|||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The <xref:Microsoft.Maui.Controls.Style> that contains the `Selected` <xref:Microsoft.Maui.Controls.VisualState> must have a `TargetType` property value that's the type of the root element of the `DataTemplate`, which is set as the `ItemTemplate` property value.
|
||||
> The <xref:Microsoft.Maui.Controls.Style> that contains the `Selected` <xref:Microsoft.Maui.Controls.VisualState> must have a `TargetType` property value that's the type of the root element of the <xref:Microsoft.Maui.Controls.DataTemplate>, which is set as the `ItemTemplate` property value.
|
||||
|
||||
In this example, the `Style.TargetType` property value is set to <xref:Microsoft.Maui.Controls.Grid> because the root element of the `ItemTemplate` is a <xref:Microsoft.Maui.Controls.Grid>. The `Selected` <xref:Microsoft.Maui.Controls.VisualState> specifies that when an item in the <xref:Microsoft.Maui.Controls.CollectionView> is selected, the `BackgroundColor` of the item will be set to `LightSkyBlue`:
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Content
|
|||
|
||||
The <xref:Microsoft.Maui.Controls.ContentView> class defines a `Content` property, of type <xref:Microsoft.Maui.Controls.View>, which represents the content of the <xref:Microsoft.Maui.Controls.ContentView>. This property is backed by a <xref:Microsoft.Maui.Controls.BindableProperty> object, which means that it can be the target of data bindings, and styled.
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ContentView> class derives from the `TemplatedView` class, which defines the `ControlTemplate` bindable property, of type `ControlTemplate`, which defines the appearance of the control. For more information about the `ControlTemplate` property, see [Customize appearance with a ControlTemplate](#customize-appearance-with-a-controltemplate).
|
||||
The <xref:Microsoft.Maui.Controls.ContentView> class derives from the `TemplatedView` class, which defines the <xref:Microsoft.Maui.Controls.ControlTemplate> bindable property, of type <xref:Microsoft.Maui.Controls.ControlTemplate>, which defines the appearance of the control. For more information about the <xref:Microsoft.Maui.Controls.ControlTemplate> property, see [Customize appearance with a ControlTemplate](#customize-appearance-with-a-controltemplate).
|
||||
|
||||
> [!NOTE]
|
||||
> A <xref:Microsoft.Maui.Controls.ContentView> can only contain a single child.
|
||||
|
|
@ -40,9 +40,9 @@ The `CardView` custom control defines the following properties:
|
|||
- `CardTitle`, of type `string`, which represents the title shown on the card.
|
||||
- `CardDescription`, of type `string`, which represents the description shown on the card.
|
||||
- `IconImageSource`, of type `ImageSource`, which represents the image shown on the card.
|
||||
- `IconBackgroundColor`, of type `Color`, which represents the background color for the image shown on the card.
|
||||
- `BorderColor`, of type `Color`, which represents the color of the card border, image border, and divider line.
|
||||
- `CardColor`, of type `Color`, which represents the background color of the card.
|
||||
- `IconBackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the background color for the image shown on the card.
|
||||
- `BorderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the color of the card border, image border, and divider line.
|
||||
- `CardColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the background color of the card.
|
||||
|
||||
Each property is backed by a <xref:Microsoft.Maui.Controls.BindableProperty> instance.
|
||||
|
||||
|
|
@ -133,9 +133,9 @@ The following screenshot shows multiple `CardView` objects:
|
|||
|
||||
## Customize appearance with a ControlTemplate
|
||||
|
||||
A custom control that derives from the <xref:Microsoft.Maui.Controls.ContentView> class can define its UI using XAML or code, or may not define its UI at all. A `ControlTemplate` can be used to override the control's appearance, regardless of how that appearance is defined.
|
||||
A custom control that derives from the <xref:Microsoft.Maui.Controls.ContentView> class can define its UI using XAML or code, or may not define its UI at all. A <xref:Microsoft.Maui.Controls.ControlTemplate> can be used to override the control's appearance, regardless of how that appearance is defined.
|
||||
|
||||
For example, a `CardView` layout might occupy too much space for some use cases. A `ControlTemplate` can be used to override the `CardView` layout to provide a more compact view, suitable for a condensed list:
|
||||
For example, a `CardView` layout might occupy too much space for some use cases. A <xref:Microsoft.Maui.Controls.ControlTemplate> can be used to override the `CardView` layout to provide a more compact view, suitable for a condensed list:
|
||||
|
||||
```xaml
|
||||
<ContentPage.Resources>
|
||||
|
|
@ -167,7 +167,7 @@ For example, a `CardView` layout might occupy too much space for some use cases.
|
|||
</ContentPage.Resources>
|
||||
```
|
||||
|
||||
Data binding in a `ControlTemplate` uses the `TemplateBinding` markup extension to specify bindings. The `ControlTemplate` property can then be set to the defined `ControlTemplate` object, by using its `x:Key` value. The following example shows the `ControlTemplate` property set on a `CardView` instance:
|
||||
Data binding in a <xref:Microsoft.Maui.Controls.ControlTemplate> uses the `TemplateBinding` markup extension to specify bindings. The <xref:Microsoft.Maui.Controls.ControlTemplate> property can then be set to the defined <xref:Microsoft.Maui.Controls.ControlTemplate> object, by using its `x:Key` value. The following example shows the <xref:Microsoft.Maui.Controls.ControlTemplate> property set on a `CardView` instance:
|
||||
|
||||
```xaml
|
||||
<controls:CardView ControlTemplate="{StaticResource CardViewCompressed}" />
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.DatePic
|
|||
- `MaximumDate` of type `DateTime`, which defaults to the last day of the year 2100.
|
||||
- `Date` of type `DateTime`, the selected date, which defaults to the value [`DateTime.Today`](xref:System.DateTime.Today).
|
||||
- `Format` of type `string`, a [standard](/dotnet/standard/base-types/standard-date-and-time-format-strings/) or [custom](/dotnet/standard/base-types/custom-date-and-time-format-strings/) .NET formatting string, which defaults to "D", the long date pattern.
|
||||
- `TextColor` of type `Color`, the color used to display the selected date.
|
||||
- `TextColor` of type <xref:Microsoft.Maui.Graphics.Color>, the color used to display the selected date.
|
||||
- `FontAttributes` of type `FontAttributes`, which defaults to `FontAtributes.None`.
|
||||
- `FontFamily` of type `string`, which defaults to `null`.
|
||||
- `FontSize` of type `double`, which defaults to -1.0.
|
||||
|
|
|
|||
|
|
@ -20,10 +20,10 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Editor>
|
|||
- `HorizontalTextAlignment`, of type `TextAlignment`, defines the horizontal alignment of the text.
|
||||
- `IsTextPredictionEnabled`, of type `bool`, controls whether text prediction and automatic text correction is enabled.
|
||||
- `Placeholder`, of type `string`, defines the text that's displayed when the control is empty.
|
||||
- `PlaceholderColor`, of type `Color`, defines the color of the placeholder text.
|
||||
- `PlaceholderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the placeholder text.
|
||||
- `SelectionLength`, of type `int`, represents the length of selected text within the editor.
|
||||
- `Text`, of type `string`, defines the text entered into the editor.
|
||||
- `TextColor`, of type `Color`, defines the color of the entered text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the entered text.
|
||||
- `VerticalTextAlignment`, of type `TextAlignment`, defines the vertical alignment of the text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -22,13 +22,13 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Entry>
|
|||
- `IsPassword`, of type `bool`, specifies whether the entry should visually obscure typed text.
|
||||
- `IsTextPredictionEnabled`, of type `bool`, controls whether text prediction and automatic text correction is enabled.
|
||||
- `Placeholder`, of type `string`, defines the text that's displayed when the control is empty.
|
||||
- `PlaceholderColor`, of type `Color`, defines the color of the placeholder text.
|
||||
- `PlaceholderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the placeholder text.
|
||||
- `ReturnCommand`, of type `ICommand`, defines the command to be executed when the return key is pressed.
|
||||
- `ReturnCommandParameter`, of type `object`, specifies the parameter for the `ReturnCommand`.
|
||||
- `ReturnType`, of type `ReturnType`, specifies the appearance of the return button.
|
||||
- `SelectionLength`, of type `int`, represents the length of selected text within the entry.
|
||||
- `Text`, of type `string`, defines the text entered into the entry.
|
||||
- `TextColor`, of type `Color`, defines the color of the entered text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the entered text.
|
||||
- `VerticalTextAlignment`, of type `TextAlignment`, defines the vertical alignment of the text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Frame>
|
|||
|
||||
The <xref:Microsoft.Maui.Controls.Frame> class defines the following properties:
|
||||
|
||||
- `BorderColor`, of type `Color`, determines the color of the <xref:Microsoft.Maui.Controls.Frame> border.
|
||||
- `BorderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, determines the color of the <xref:Microsoft.Maui.Controls.Frame> border.
|
||||
- `CornerRadius`, of type `float`, determines the rounded radius of the corner.
|
||||
- `HasShadow`, of type `bool`, determines whether the frame has a drop shadow.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.ImageBu
|
|||
<xref:Microsoft.Maui.Controls.ImageButton> defines the following properties:
|
||||
|
||||
- `Aspect`, of type `Aspect`, determines how the image will be scaled to fit the display area.
|
||||
- `BorderColor`, of type `Color`, describes the border color of the button.
|
||||
- `BorderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, describes the border color of the button.
|
||||
- `BorderWidth`, of type `double`, defines the width of the button's border.
|
||||
- `Command`, of type `ICommand`, defines the command that's executed when the button is tapped.
|
||||
- `CommandParameter`, of type `object`, is the parameter that's passed to `Command`.
|
||||
|
|
|
|||
|
|
@ -16,15 +16,15 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Indicat
|
|||
|
||||
- `Count`, of type `int`, the number of indicators.
|
||||
- `HideSingle`, of type `bool`, indicates whether the indicator should be hidden when only one exists. The default value is `true`.
|
||||
- `IndicatorColor`, of type `Color`, the color of the indicators.
|
||||
- `IndicatorColor`, of type <xref:Microsoft.Maui.Graphics.Color>, the color of the indicators.
|
||||
- `IndicatorSize`, of type `double`, the size of the indicators. The default value is 6.0.
|
||||
- `IndicatorLayout`, of type `Layout<View>`, defines the layout class used to render the <xref:Microsoft.Maui.Controls.IndicatorView>. This property is set by .NET MAUI, and does not typically need to be set by developers.
|
||||
- `IndicatorTemplate`, of type `DataTemplate`, the template that defines the appearance of each indicator.
|
||||
- `IndicatorTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, the template that defines the appearance of each indicator.
|
||||
- `IndicatorsShape`, of type `IndicatorShape`, the shape of each indicator.
|
||||
- `ItemsSource`, of type `IEnumerable`, the collection that indicators will be displayed for. This property will automatically be set when the `CarouselView.IndicatorView` property is set.
|
||||
- `MaximumVisible`, of type `int`, the maximum number of visible indicators. The default value is `int.MaxValue`.
|
||||
- `Position`, of type `int`, the currently selected indicator index. This property uses a `TwoWay` binding. This property will automatically be set when the `CarouselView.IndicatorView` property is set.
|
||||
- `SelectedIndicatorColor`, of type `Color`, the color of the indicator that represents the current item in the <xref:Microsoft.Maui.Controls.CarouselView>.
|
||||
- `SelectedIndicatorColor`, of type <xref:Microsoft.Maui.Graphics.Color>, the color of the indicator that represents the current item in the <xref:Microsoft.Maui.Controls.CarouselView>.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ The following example shows an <xref:Microsoft.Maui.Controls.IndicatorView> conf
|
|||
|
||||
## Define indicator appearance
|
||||
|
||||
The appearance of each indicator can be defined by setting the `IndicatorView.IndicatorTemplate` property to a `DataTemplate`:
|
||||
The appearance of each indicator can be defined by setting the `IndicatorView.IndicatorTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<StackLayout>
|
||||
|
|
@ -120,7 +120,7 @@ The appearance of each indicator can be defined by setting the `IndicatorView.In
|
|||
</StackLayout>
|
||||
```
|
||||
|
||||
The elements specified in the `DataTemplate` define the appearance of each indicator. In this example, each indicator is a <xref:Microsoft.Maui.Controls.Label> that displays a font icon.
|
||||
The elements specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each indicator. In this example, each indicator is a <xref:Microsoft.Maui.Controls.Label> that displays a font icon.
|
||||
|
||||
The following screenshot shows indicators rendered using a font icon:
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Label>
|
|||
- `MaxLines`, of type `int`, indicates the maximum number of lines allowed in the <xref:Microsoft.Maui.Controls.Label>.
|
||||
- `Padding`, of type `Thickness`, determines the label's padding.
|
||||
- `Text`, of type `string`, defines the text displayed as the content of the label.
|
||||
- `TextColor`, of type `Color`, defines the color of the displayed text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the displayed text.
|
||||
- `TextDecorations`, of type `TextDecorations`, specifies the text decorations (underline and strikethrough) that can be applied.
|
||||
- `TextTransform`, of type `TextTransform`, specifies the casing of the displayed text.
|
||||
- `TextType`, of type `TextType`, determines whether the <xref:Microsoft.Maui.Controls.Label> should display plain text or HTML text.
|
||||
|
|
@ -247,7 +247,7 @@ The following example shows transforming text to uppercase:
|
|||
|
||||
<xref:Microsoft.Maui.Controls.Span> defines the following properties:
|
||||
|
||||
- `BackgroundColor`, of type `Color`, which represents the color of the span background.
|
||||
- `BackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which represents the color of the span background.
|
||||
- `CharacterSpacing`, of type `double`, sets the spacing between characters in the displayed text.
|
||||
- `FontAttributes`, of type `FontAttributes`, determines text style.
|
||||
- `FontAutoScalingEnabled`, of type `bool`, defines whether the text will reflect scaling preferences set in the operating system. The default value of this property is `true`.
|
||||
|
|
@ -256,7 +256,7 @@ The following example shows transforming text to uppercase:
|
|||
- `LineHeight`, of type `double`, specifies the multiplier to apply to the default line height when displaying text.
|
||||
- `Style`, of type <xref:Microsoft.Maui.Controls.Style>, which is the style to apply to the span.
|
||||
- `Text`, of type `string`, defines the text displayed as the content of the <xref:Microsoft.Maui.Controls.Span>.
|
||||
- `TextColor`, of type `Color`, defines the color of the displayed text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the displayed text.
|
||||
- `TextDecorations`, of type `TextDecorations`, specifies the text decorations (underline and strikethrough) that can be applied.
|
||||
- `TextTransform`, of type `TextTransform`, specifies the casing of the displayed text.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,31 +8,31 @@ ms.date: 03/10/2022
|
|||
|
||||
[ Browse the sample](/samples/dotnet/maui-samples/userinterface-listview)
|
||||
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.ListView> displays a scrollable vertical list of selectable data items. While <xref:Microsoft.Maui.Controls.ListView> manages the appearance of the list, the appearance of each item in the list is defined by a `DataTemplate` that uses a <xref:Microsoft.Maui.Controls.Cell> to display items. .NET MAUI includes cell types to display combinations of text and images, and you can also define custom cells that display any content you want. <xref:Microsoft.Maui.Controls.ListView> also includes support for displaying headers and footers, grouped data, pull-to-refresh, and context menu items.
|
||||
The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.ListView> displays a scrollable vertical list of selectable data items. While <xref:Microsoft.Maui.Controls.ListView> manages the appearance of the list, the appearance of each item in the list is defined by a <xref:Microsoft.Maui.Controls.DataTemplate> that uses a <xref:Microsoft.Maui.Controls.Cell> to display items. .NET MAUI includes cell types to display combinations of text and images, and you can also define custom cells that display any content you want. <xref:Microsoft.Maui.Controls.ListView> also includes support for displaying headers and footers, grouped data, pull-to-refresh, and context menu items.
|
||||
|
||||
The <xref:Microsoft.Maui.Controls.ListView> class derives from the `ItemsView<Cell>` class, from which it inherits the following properties:
|
||||
|
||||
- `ItemsSource`, of type `IEnumerable`, specifies the collection of items to be displayed, and has a default value of `null`.
|
||||
- `ItemTemplate`, of type `DataTemplate`, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
- `ItemTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the template to apply to each item in the collection of items to be displayed.
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> defines the following properties:
|
||||
|
||||
- `Footer`, of type `object`, specifies the string or view that will be displayed at the end of the list.
|
||||
- `FooterTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Footer`.
|
||||
- `GroupHeaderTemplate`, of type `DataTemplate`, defines the `DataTemplate` used to define the appearance of the header of each group. This property is mutually exclusive with the `GroupDisplayBinding` property. Therefore, setting this property will set `GroupDisplayBinding` to `null`.
|
||||
- `FooterTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Footer`.
|
||||
- `GroupHeaderTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, defines the <xref:Microsoft.Maui.Controls.DataTemplate> used to define the appearance of the header of each group. This property is mutually exclusive with the `GroupDisplayBinding` property. Therefore, setting this property will set `GroupDisplayBinding` to `null`.
|
||||
- `HasUnevenRows`, of type `bool`, indicates whether items in the list can have rows of different heights. The default value of this property is `false`.
|
||||
- `Header`, of type `object`, specifies the string or view that will be displayed at the start of the list.
|
||||
- `HeaderTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Header`.
|
||||
- `HeaderTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Header`.
|
||||
- `HorizontalScrollBarVisibility`, of type `ScrollBarVisibility`, indicates when the horizontal scroll bar will be visible.
|
||||
- `IsGroupedEnabled`, of type `bool`, indicates whether the underlying data should be displayed in groups. The default value of this property is `false`.
|
||||
- `IsPullToRefreshEnabled`, of type `bool`, indicates whether the user can swipe down to cause the <xref:Microsoft.Maui.Controls.ListView> to refresh its data. The default value of this property is `false`.
|
||||
- `IsRefreshing`, of type `bool`, indicates whether the <xref:Microsoft.Maui.Controls.ListView> is currently refreshing. The default value of this property is `false`.
|
||||
- `RefreshCommand`, of type `ICommand`, represents the command that will be executed when a refresh is triggered.
|
||||
- `RefreshControlColor`, of type `Color`, determines the color of the refresh visualization that's shown while a refresh occurs.
|
||||
- `RefreshControlColor`, of type <xref:Microsoft.Maui.Graphics.Color>, determines the color of the refresh visualization that's shown while a refresh occurs.
|
||||
- `RowHeight`, of type `int`, determines the height of each row when `HasUnevenRows` is `false`.
|
||||
- `SelectedItem`, of type `object`, represents the currently selected item in the <xref:Microsoft.Maui.Controls.ListView>.
|
||||
- `SelectionMode`, of type `ListViewSelectionMode`, indicates whether items can be selected in the <xref:Microsoft.Maui.Controls.ListView> or not. The default value of this property is `Single`.
|
||||
- `SeparatorColor`, of type `Color`, defines the color of the bar that separates items in the list.
|
||||
- `SeparatorColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the bar that separates items in the list.
|
||||
- `SeparatorVisibility`, of type `SeparatorVisibility`, defines whether separators are visible between items.
|
||||
- `VerticalScrollBarVisibility`, of type `ScrollBarVisibility`, indicates when the vertical scroll bar will be visible.
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ For more information about data binding, see [Data binding](~/fundamentals/data-
|
|||
|
||||
## Define item appearance
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> can be defined by setting the `ItemTemplate` property to a `DataTemplate`:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> can be defined by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ListView ItemsSource="{Binding Monkeys}">
|
||||
|
|
@ -119,7 +119,7 @@ The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> can b
|
|||
</ListView>
|
||||
```
|
||||
|
||||
The elements specified in the `DataTemplate` define the appearance of each item in the list, and the child of the `DataTemplate` must be a <xref:Microsoft.Maui.Controls.Cell> object. In the example, layout within the `DataTemplate` is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and two <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
The elements specified in the <xref:Microsoft.Maui.Controls.DataTemplate> define the appearance of each item in the list, and the child of the <xref:Microsoft.Maui.Controls.DataTemplate> must be a <xref:Microsoft.Maui.Controls.Cell> object. In the example, layout within the <xref:Microsoft.Maui.Controls.DataTemplate> is managed by a <xref:Microsoft.Maui.Controls.Grid>. The <xref:Microsoft.Maui.Controls.Grid> contains an <xref:Microsoft.Maui.Controls.Image> object, and two <xref:Microsoft.Maui.Controls.Label> objects, that all bind to properties of the `Monkey` class:
|
||||
|
||||
```csharp
|
||||
public class Monkey
|
||||
|
|
@ -139,7 +139,7 @@ For more information about data templates, see [Data templates](~/fundamentals/d
|
|||
|
||||
### Cells
|
||||
|
||||
The appearance of each item in a <xref:Microsoft.Maui.Controls.ListView> is defined by a `DataTemplate`, and the `DataTemplate` must reference a <xref:Microsoft.Maui.Controls.Cell> class to display items. Each cell represents an item of data in the <xref:Microsoft.Maui.Controls.ListView>. .NET MAUI includes the following built-in cells:
|
||||
The appearance of each item in a <xref:Microsoft.Maui.Controls.ListView> is defined by a <xref:Microsoft.Maui.Controls.DataTemplate>, and the <xref:Microsoft.Maui.Controls.DataTemplate> must reference a <xref:Microsoft.Maui.Controls.Cell> class to display items. Each cell represents an item of data in the <xref:Microsoft.Maui.Controls.ListView>. .NET MAUI includes the following built-in cells:
|
||||
|
||||
- <xref:Microsoft.Maui.Controls.TextCell>, which displays primary and secondary text on separate lines.
|
||||
- <xref:Microsoft.Maui.Controls.ImageCell>, which displays an image with primary and secondary text on separate lines.
|
||||
|
|
@ -154,9 +154,9 @@ Typically, <xref:Microsoft.Maui.Controls.SwitchCell> and <xref:Microsoft.Maui.Co
|
|||
A <xref:Microsoft.Maui.Controls.TextCell> displays primary and secondary text on separate lines. <xref:Microsoft.Maui.Controls.TextCell> defines the following properties:
|
||||
|
||||
- `Text`, of type `string`, defines the primary text to be displayed.
|
||||
- `TextColor`, of type `Color`, represents the color of the primary text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, represents the color of the primary text.
|
||||
- `Detail`, of type `string`, defines the secondary text to be displayed.
|
||||
- `DetailColor`, of type `Color`, indicates the color of the secondary text.
|
||||
- `DetailColor`, of type <xref:Microsoft.Maui.Graphics.Color>, indicates the color of the secondary text.
|
||||
- `Command`, of type `ICommand`, defines the command that's executed when the cell is tapped.
|
||||
- `CommandParameter`, of type `object`, represents the parameter that's passed to the command.
|
||||
|
||||
|
|
@ -252,7 +252,7 @@ The following screenshot shows the result of templating each item in the list:
|
|||
|
||||
## Choose item appearance at runtime
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> can be chosen at runtime, based on the item value, by setting the `ItemTemplate` property to a `DataTemplateSelector` object:
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> can be chosen at runtime, based on the item value, by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector> object:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -297,7 +297,7 @@ public class MonkeyDataTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template, which displays the monkey name and location in teal, when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays the monkey name and location in silver:
|
||||
The `MonkeyDataTemplateSelector` class defines `AmericanMonkey` and `OtherMonkey` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` override returns the `AmericanMonkey` template, which displays the monkey name and location in teal, when the monkey name contains "America". When the monkey name doesn't contain "America", the `OnSelectTemplate` override returns the `OtherMonkey` template, which displays the monkey name and location in silver:
|
||||
|
||||
:::image type="content" source="media/listview/datatemplateselector.png" alt-text="Screenshot of ListView runtime item template selection.":::
|
||||
|
||||
|
|
@ -363,7 +363,7 @@ To conserve memory, the native <xref:Microsoft.Maui.Controls.ListView> equivalen
|
|||
|
||||
- `RetainElement`, specifies that the <xref:Microsoft.Maui.Controls.ListView> will generate a cell for each item in the list.
|
||||
- `RecycleElement`, specifies that the <xref:Microsoft.Maui.Controls.ListView> will attempt to minimize its memory footprint and execution speed by recycling list cells.
|
||||
- `RecycleElementAndDataTemplate`, as `RecycleElement` while also ensuring that when a <xref:Microsoft.Maui.Controls.ListView> uses a `DataTemplateSelector`, `DataTemplate` objects are cached by the type of item in the list.
|
||||
- `RecycleElementAndDataTemplate`, as `RecycleElement` while also ensuring that when a <xref:Microsoft.Maui.Controls.ListView> uses a <xref:Microsoft.Maui.Controls.DataTemplateSelector>, <xref:Microsoft.Maui.Controls.DataTemplate> objects are cached by the type of item in the list.
|
||||
|
||||
<!-- > [!NOTE]
|
||||
> Windows ignores the `RetainElement` caching strategy, because it always uses caching to improve performance. Therefore, by default it behaves as if the `RecycleElement` caching strategy is applied. -->
|
||||
|
|
@ -416,17 +416,17 @@ public class CustomCell : ViewCell
|
|||
|
||||
#### Recycle elements with a DataTemplateSelector
|
||||
|
||||
When a <xref:Microsoft.Maui.Controls.ListView> uses a `DataTemplateSelector` to select a `DataTemplate`, the `RecycleElement` caching strategy does not cache `DataTemplate` objects. Instead, a `DataTemplate` is selected for each item of data in the list.
|
||||
When a <xref:Microsoft.Maui.Controls.ListView> uses a <xref:Microsoft.Maui.Controls.DataTemplateSelector> to select a <xref:Microsoft.Maui.Controls.DataTemplate>, the `RecycleElement` caching strategy does not cache <xref:Microsoft.Maui.Controls.DataTemplate> objects. Instead, a <xref:Microsoft.Maui.Controls.DataTemplate> is selected for each item of data in the list.
|
||||
|
||||
> [!NOTE]
|
||||
> The `RecycleElement` caching strategy requires that when a `DataTemplateSelector` is asked to select a `DataTemplate` that each `DataTemplate` must return the same <xref:Microsoft.Maui.Controls.ViewCell> type. For example, given a <xref:Microsoft.Maui.Controls.ListView> with a `DataTemplateSelector` that can return either `MyDataTemplateA` (where `MyDataTemplateA` returns a <xref:Microsoft.Maui.Controls.ViewCell> of type `MyViewCellA`), or `MyDataTemplateB` (where `MyDataTemplateB` returns a <xref:Microsoft.Maui.Controls.ViewCell> of type `MyViewCellB`), when `MyDataTemplateA` is returned it must return `MyViewCellA` or an exception will be thrown.
|
||||
> The `RecycleElement` caching strategy requires that when a <xref:Microsoft.Maui.Controls.DataTemplateSelector> is asked to select a <xref:Microsoft.Maui.Controls.DataTemplate> that each <xref:Microsoft.Maui.Controls.DataTemplate> must return the same <xref:Microsoft.Maui.Controls.ViewCell> type. For example, given a <xref:Microsoft.Maui.Controls.ListView> with a <xref:Microsoft.Maui.Controls.DataTemplateSelector> that can return either `MyDataTemplateA` (where `MyDataTemplateA` returns a <xref:Microsoft.Maui.Controls.ViewCell> of type `MyViewCellA`), or `MyDataTemplateB` (where `MyDataTemplateB` returns a <xref:Microsoft.Maui.Controls.ViewCell> of type `MyViewCellB`), when `MyDataTemplateA` is returned it must return `MyViewCellA` or an exception will be thrown.
|
||||
|
||||
### Recycle elements with DataTemplates
|
||||
|
||||
The `RecycleElementAndDataTemplate` caching strategy builds on the `RecycleElement` caching strategy by additionally ensuring that when a <xref:Microsoft.Maui.Controls.ListView> uses a `DataTemplateSelector` to select a `DataTemplate`, `DataTemplate` objects are cached by the type of item in the list. Therefore, `DataTemplate` objects are selected once per item type, instead of once per item instance.
|
||||
The `RecycleElementAndDataTemplate` caching strategy builds on the `RecycleElement` caching strategy by additionally ensuring that when a <xref:Microsoft.Maui.Controls.ListView> uses a <xref:Microsoft.Maui.Controls.DataTemplateSelector> to select a <xref:Microsoft.Maui.Controls.DataTemplate>, <xref:Microsoft.Maui.Controls.DataTemplate> objects are cached by the type of item in the list. Therefore, <xref:Microsoft.Maui.Controls.DataTemplate> objects are selected once per item type, instead of once per item instance.
|
||||
|
||||
> [!NOTE]
|
||||
> The `RecycleElementAndDataTemplate` caching strategy requires that `DataTemplate` objects returned by the `DataTemplateSelector` must use the `DataTemplate` constructor that takes a `Type`.
|
||||
> The `RecycleElementAndDataTemplate` caching strategy requires that <xref:Microsoft.Maui.Controls.DataTemplate> objects returned by the <xref:Microsoft.Maui.Controls.DataTemplateSelector> must use the <xref:Microsoft.Maui.Controls.DataTemplate> constructor that takes a `Type`.
|
||||
|
||||
### Set the caching strategy
|
||||
|
||||
|
|
@ -476,14 +476,14 @@ Then the `ListViewCachingStrategy` enumeration value can be specified from XAML
|
|||
|
||||
## Headers and footers
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> can present a header and footer that scroll with the items in the list. The header and footer can be strings, views, or `DataTemplate` objects.
|
||||
<xref:Microsoft.Maui.Controls.ListView> can present a header and footer that scroll with the items in the list. The header and footer can be strings, views, or <xref:Microsoft.Maui.Controls.DataTemplate> objects.
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> defines the following properties for specifying the header and footer:
|
||||
|
||||
- `Header`, of type `object`, specifies the string, binding, or view that will be displayed at the start of the list.
|
||||
- `HeaderTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Header`.
|
||||
- `HeaderTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Header`.
|
||||
- `Footer`, of type `object`, specifies the string, binding, or view that will be displayed at the end of the list.
|
||||
- `FooterTemplate`, of type `DataTemplate`, specifies the `DataTemplate` to use to format the `Footer`.
|
||||
- `FooterTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to use to format the `Footer`.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that the properties can be targets of data bindings.
|
||||
|
||||
|
|
@ -535,7 +535,7 @@ The following screenshot shows the resulting header:
|
|||
|
||||
### Display a templated header and footer
|
||||
|
||||
The `HeaderTemplate` and `FooterTemplate` properties can be set to `DataTemplate` objects that are used to format the header and footer. In this scenario, the `Header` and `Footer` properties must bind to the current source for the templates to be applied, as shown in the following example:
|
||||
The `HeaderTemplate` and `FooterTemplate` properties can be set to <xref:Microsoft.Maui.Controls.DataTemplate> objects that are used to format the header and footer. In this scenario, the `Header` and `Footer` properties must bind to the current source for the templates to be applied, as shown in the following example:
|
||||
|
||||
```xaml
|
||||
<ListView ItemsSource="{Binding Monkeys}"
|
||||
|
|
@ -583,11 +583,11 @@ In addition, when the separator is enabled, it's color can be set with the `Sepa
|
|||
|
||||
## Size items
|
||||
|
||||
By default, all items in a <xref:Microsoft.Maui.Controls.ListView> have the same height, which is derived from the contents of the `DataTemplate` that defines the appearance of each item. However, this behavior can be changed with the `HasUnevenRows` and `RowHeight` properties. By default, the `HasUnevenRows` property is `false`.
|
||||
By default, all items in a <xref:Microsoft.Maui.Controls.ListView> have the same height, which is derived from the contents of the <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each item. However, this behavior can be changed with the `HasUnevenRows` and `RowHeight` properties. By default, the `HasUnevenRows` property is `false`.
|
||||
|
||||
The `RowHeight` property can be set to an `int` that represents the height of each item in the <xref:Microsoft.Maui.Controls.ListView>, provided that `HasUnevenRows` is `false`. When `HasUnevenRows` is set to `true`, each item in the <xref:Microsoft.Maui.Controls.ListView> can have a different height. The height of each item will be derived from the contents of the item's `DataTemplate`, and so each item will be sized to its content.
|
||||
The `RowHeight` property can be set to an `int` that represents the height of each item in the <xref:Microsoft.Maui.Controls.ListView>, provided that `HasUnevenRows` is `false`. When `HasUnevenRows` is set to `true`, each item in the <xref:Microsoft.Maui.Controls.ListView> can have a different height. The height of each item will be derived from the contents of the item's <xref:Microsoft.Maui.Controls.DataTemplate>, and so each item will be sized to its content.
|
||||
|
||||
Individual <xref:Microsoft.Maui.Controls.ListView> items can be programmatically resized at runtime by changing layout related properties of elements within the `DataTemplate`, provided that the `HasUnevenRows` property is `true`. The following example changes the height of an <xref:Microsoft.Maui.Controls.Image> object when it's tapped:
|
||||
Individual <xref:Microsoft.Maui.Controls.ListView> items can be programmatically resized at runtime by changing layout related properties of elements within the <xref:Microsoft.Maui.Controls.DataTemplate>, provided that the `HasUnevenRows` property is `true`. The following example changes the height of an <xref:Microsoft.Maui.Controls.Image> object when it's tapped:
|
||||
|
||||
```csharp
|
||||
void OnImageTapped(object sender, EventArgs args)
|
||||
|
|
@ -781,7 +781,7 @@ listView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");
|
|||
// ...
|
||||
```
|
||||
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> is defined by setting its `ItemTemplate` property to a `DataTemplate`. For more information, see [Define item appearance](#define-item-appearance).
|
||||
The appearance of each item in the <xref:Microsoft.Maui.Controls.ListView> is defined by setting its `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>. For more information, see [Define item appearance](#define-item-appearance).
|
||||
|
||||
The following screenshot shows the <xref:Microsoft.Maui.Controls.ListView> displaying grouped data:
|
||||
|
||||
|
|
@ -792,7 +792,7 @@ The following screenshot shows the <xref:Microsoft.Maui.Controls.ListView> displ
|
|||
|
||||
### Customize the group header
|
||||
|
||||
The appearance of each group header can be customized by setting the `ListView.GroupHeaderTemplate` property to a `DataTemplate`:
|
||||
The appearance of each group header can be customized by setting the `ListView.GroupHeaderTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ListView ItemsSource="{Binding Animals}"
|
||||
|
|
@ -820,7 +820,7 @@ In this example, each group header is set to a <xref:Microsoft.Maui.Controls.Lab
|
|||
|
||||
### Group without templates
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> can display correctly grouped data without setting the `ItemTemplate` property to a `DataTemplate`:
|
||||
<xref:Microsoft.Maui.Controls.ListView> can display correctly grouped data without setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<ListView ItemsSource="{Binding Animals}"
|
||||
|
|
@ -947,7 +947,7 @@ listView.ScrollTo(monkey, position: ScrollToPosition.End, animate: true);
|
|||
|
||||
## Add context menus
|
||||
|
||||
<xref:Microsoft.Maui.Controls.ListView> supports context menus items, which are defined as `MenuItem` objects that are added to the `ViewCell.ContextActions` collection in the `DataTemplate` for each item:
|
||||
<xref:Microsoft.Maui.Controls.ListView> supports context menus items, which are defined as `MenuItem` objects that are added to the `ViewCell.ContextActions` collection in the <xref:Microsoft.Maui.Controls.DataTemplate> for each item:
|
||||
|
||||
```xaml
|
||||
<ListView x:Name="listView"
|
||||
|
|
|
|||
|
|
@ -154,8 +154,8 @@ The <xref:Microsoft.Maui.Controls.Maps.Map> class defines the following properti
|
|||
|
||||
- `IsShowingUser`, of type `bool`, indicates whether the map is showing the user's current location.
|
||||
- `ItemsSource`, of type `IEnumerable`, which specifies the collection of `IEnumerable` pin items to be displayed.
|
||||
- `ItemTemplate`, of type `DataTemplate`, which specifies the `DataTemplate` to apply to each item in the collection of displayed pins.
|
||||
- `ItemTemplateSelector`, of type `DataTemplateSelector`, which specifies the `DataTemplateSelector` that will be used to choose a `DataTemplate` for a pin at runtime.
|
||||
- `ItemTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, which specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to apply to each item in the collection of displayed pins.
|
||||
- `ItemTemplateSelector`, of type <xref:Microsoft.Maui.Controls.DataTemplateSelector>, which specifies the <xref:Microsoft.Maui.Controls.DataTemplateSelector> that will be used to choose a <xref:Microsoft.Maui.Controls.DataTemplate> for a pin at runtime.
|
||||
- `IsScrollEnabled`, of type `bool`, determines whether the map is allowed to scroll.
|
||||
- `IsTrafficEnabled`, of type `bool`, indicates whether traffic data is overlaid on the map.
|
||||
- `IsZoomEnabled`, of type `bool`, determines whether the map is allowed to zoom.
|
||||
|
|
@ -645,8 +645,8 @@ However, setting the `Pin.Type` property to any `PinType` member does not change
|
|||
The <xref:Microsoft.Maui.Controls.Maps.Map> class defines the following bindable properties:
|
||||
|
||||
- `ItemsSource`, of type `IEnumerable`, which specifies the collection of `IEnumerable` pin items to be displayed.
|
||||
- `ItemTemplate`, of type `DataTemplate`, which specifies the `DataTemplate` to apply to each item in the collection of displayed pins.
|
||||
- `ItemTemplateSelector`, of type `DataTemplateSelector`, which specifies the `DataTemplateSelector` that will be used to choose a `DataTemplate` for a pin at runtime.
|
||||
- `ItemTemplate`, of type <xref:Microsoft.Maui.Controls.DataTemplate>, which specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to apply to each item in the collection of displayed pins.
|
||||
- `ItemTemplateSelector`, of type <xref:Microsoft.Maui.Controls.DataTemplateSelector>, which specifies the <xref:Microsoft.Maui.Controls.DataTemplateSelector> that will be used to choose a <xref:Microsoft.Maui.Controls.DataTemplate> for a pin at runtime.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `ItemTemplate` property takes precedence when both the `ItemTemplate` and `ItemTemplateSelector` properties are set.
|
||||
|
|
@ -675,7 +675,7 @@ A <xref:Microsoft.Maui.Controls.Maps.Map> can be populated with pins by using da
|
|||
|
||||
The `ItemsSource` property data binds to the `Positions` property of the connected viewmodel, which returns an `ObservableCollection` of `Position` objects, which is a custom type. Each `Position` object defines `Address` and `Description` properties, of type `string`, and a `Location` property, of type `Location`.
|
||||
|
||||
The appearance of each item in the `IEnumerable` collection is defined by setting the `ItemTemplate` property to a `DataTemplate` that contains a `Pin` object that data binds to appropriate properties.
|
||||
The appearance of each item in the `IEnumerable` collection is defined by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate> that contains a `Pin` object that data binds to appropriate properties.
|
||||
|
||||
The following screenshot shows a <xref:Microsoft.Maui.Controls.Maps.Map> displaying a `Pin` collection using data binding:
|
||||
|
||||
|
|
@ -683,7 +683,7 @@ The following screenshot shows a <xref:Microsoft.Maui.Controls.Maps.Map> display
|
|||
|
||||
#### Choose item appearance at runtime
|
||||
|
||||
The appearance of each item in the `IEnumerable` collection can be chosen at runtime, based on the item value, by setting the `ItemTemplateSelector` property to a `DataTemplateSelector`:
|
||||
The appearance of each item in the `IEnumerable` collection can be chosen at runtime, based on the item value, by setting the `ItemTemplateSelector` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector>:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...
|
||||
|
|
@ -737,7 +737,7 @@ public class MapItemTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `MapItemTemplateSelector` class defines `DefaultTemplate` and `SanFranTemplate` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` method returns the `SanFranTemplate`, which displays "Xamarin" as a label when a `Pin` is tapped, when the item has an address that contains "San Francisco". When the item doesn't have an address that contains "San Francisco", the `OnSelectTemplate` method returns the `DefaultTemplate`.
|
||||
The `MapItemTemplateSelector` class defines `DefaultTemplate` and `SanFranTemplate` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` method returns the `SanFranTemplate`, which displays "Xamarin" as a label when a `Pin` is tapped, when the item has an address that contains "San Francisco". When the item doesn't have an address that contains "San Francisco", the `OnSelectTemplate` method returns the `DefaultTemplate`.
|
||||
|
||||
> [!NOTE]
|
||||
> A use case for this functionality is binding properties of sub-classed `Pin` objects to different properties, based on the `Pin` sub-type.
|
||||
|
|
@ -752,12 +752,12 @@ For more information about data template selectors, see [Create a DataTemplateSe
|
|||
|
||||
The `Polygon`, `Polyline`, and `Circle` classes derive from the `MapElement` class, which exposes the following bindable properties:
|
||||
|
||||
- `StrokeColor` is a `Color` object that determines the line color.
|
||||
- `StrokeColor` is a <xref:Microsoft.Maui.Graphics.Color> object that determines the line color.
|
||||
- `StrokeWidth` is a `float` object that determines the line width.
|
||||
|
||||
The `Polygon` class defines an additional bindable property:
|
||||
|
||||
- `FillColor` is a `Color` object that determines the polygon's background color.
|
||||
- `FillColor` is a <xref:Microsoft.Maui.Graphics.Color> object that determines the polygon's background color.
|
||||
|
||||
In addition, the `Polygon` and `Polyline` classes both define a `GeoPath` property, which is a list of `Location` objects that specify the points of the shape.
|
||||
|
||||
|
|
@ -765,7 +765,7 @@ The `Circle` class defines the following bindable properties:
|
|||
|
||||
- `Center` is a `Location` object that defines the center of the circle, in latitude and longitude.
|
||||
- `Radius` is a `Distance` object that defines the radius of the circle in meters, kilometers, or miles.
|
||||
- `FillColor` is a `Color` property that determines the color within the circle perimeter.
|
||||
- `FillColor` is a <xref:Microsoft.Maui.Graphics.Color> property that determines the color within the circle perimeter.
|
||||
|
||||
### Create a polygon
|
||||
|
||||
|
|
|
|||
|
|
@ -19,10 +19,10 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Picker>
|
|||
- `ItemsSource` of type `IList`, the source list of items to display, which defaults to `null`.
|
||||
- `SelectedIndex` of type `int`, the index of the selected item, which defaults to -1.
|
||||
- `SelectedItem` of type `object`, the selected item, which defaults to `null`.
|
||||
- `TextColor` of type `Color`, the color used to display the text.
|
||||
- `TextColor` of type <xref:Microsoft.Maui.Graphics.Color>, the color used to display the text.
|
||||
- `TextTransform`, of type `TextTransform`, which defines whether to transform the casing of text.
|
||||
- `Title` of type `string`, which defaults to `null`.
|
||||
- `TitleColor` of type `Color`, the color used to display the `Title` text.
|
||||
- `TitleColor` of type <xref:Microsoft.Maui.Graphics.Color>, the color used to display the `Title` text.
|
||||
- `VerticalTextAlignment`, of type `TextAlignment`, is the vertical alignment of the text displayed by the <xref:Microsoft.Maui.Controls.Picker>.
|
||||
|
||||
All of the properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be styled, and the properties can be targets of data bindings. The `SelectedIndex` and `SelectedItem` properties have a default binding mode of `BindingMode.TwoWay`, which means that they can be targets of data bindings in an application that uses the Model-View-ViewModel (MVVM) pattern. For information about setting font properties, see [Fonts](~/user-interface/fonts.md).
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ The appearance of a <xref:Microsoft.Maui.Controls.ProgressBar> is platform-depen
|
|||
<xref:Microsoft.Maui.Controls.ProgressBar> defines two properties:
|
||||
|
||||
- `Progress` is a `double` value that represents the current progress as a value from 0 to 1. `Progress` values less than 0 will be clamped to 0, values greater than 1 will be clamped to 1. The default value of this property is 0.
|
||||
- `ProgressColor` is a `Color` values that defines the color of the <xref:Microsoft.Maui.Controls.ProgressBar>.
|
||||
- `ProgressColor` is a <xref:Microsoft.Maui.Graphics.Color> values that defines the color of the <xref:Microsoft.Maui.Controls.ProgressBar>.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.RadioBu
|
|||
|
||||
:::image type="content" source="media/radiobutton/radiobuttons-default.png" alt-text="Screenshot of RadioButtons.":::
|
||||
|
||||
However, on some platforms a <xref:Microsoft.Maui.Controls.RadioButton> can display a <xref:Microsoft.Maui.Controls.View>, and on all platforms the appearance of each <xref:Microsoft.Maui.Controls.RadioButton> can be redefined with a `ControlTemplate`:
|
||||
However, on some platforms a <xref:Microsoft.Maui.Controls.RadioButton> can display a <xref:Microsoft.Maui.Controls.View>, and on all platforms the appearance of each <xref:Microsoft.Maui.Controls.RadioButton> can be redefined with a <xref:Microsoft.Maui.Controls.ControlTemplate>:
|
||||
|
||||
:::image type="content" source="media/radiobutton/radiobuttons-controltemplate.png" alt-text="Screenshot of re-defined RadioButtons.":::
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ However, on some platforms a <xref:Microsoft.Maui.Controls.RadioButton> can disp
|
|||
- `IsChecked`, of type `bool`, which defines whether the <xref:Microsoft.Maui.Controls.RadioButton> is checked. This property uses a `TwoWay` binding, and has a default value of `false`.
|
||||
- `GroupName`, of type `string`, which defines the name that specifies which <xref:Microsoft.Maui.Controls.RadioButton> controls are mutually exclusive. This property has a default value of `null`.
|
||||
- `Value`, of type `object`, which defines an optional unique value associated with the <xref:Microsoft.Maui.Controls.RadioButton>.
|
||||
- `BorderColor`, of type `Color`, which defines the border stroke color.
|
||||
- `BorderColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which defines the border stroke color.
|
||||
- `BorderWidth`, of type `double`, which defines the width of the <xref:Microsoft.Maui.Controls.RadioButton> border.
|
||||
- `CharacterSpacing`, of type `double`, which defines the spacing between characters of any displayed text.
|
||||
- `CornerRadius`, of type `int`, which defines the corner radius of the <xref:Microsoft.Maui.Controls.RadioButton>.
|
||||
|
|
@ -30,7 +30,7 @@ However, on some platforms a <xref:Microsoft.Maui.Controls.RadioButton> can disp
|
|||
- `FontAutoScalingEnabled`, of type `bool`, which defines whether an app's UI reflects text scaling preferences set in the operating system. The default value of this property is `true`.
|
||||
- `FontFamily`, of type `string`, which defines the font family.
|
||||
- `FontSize`, of type `double`, which defines the font size.
|
||||
- `TextColor`, of type `Color`, which defines the color of any displayed text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, which defines the color of any displayed text.
|
||||
- `TextTransform`, of type `TextTransform`, which defines the casing of any displayed text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
@ -50,7 +50,7 @@ The appearance of a <xref:Microsoft.Maui.Controls.RadioButton> is defined by the
|
|||
|
||||
- When the `RadioButton.Content` property is assigned a `string`, it will be displayed on each platform, horizontally aligned next to the radio button circle.
|
||||
- When the `RadioButton.Content` is assigned a <xref:Microsoft.Maui.Controls.View>, it will be displayed on supported platforms (iOS, Windows), while unsupported platforms will fallback to a string representation of the <xref:Microsoft.Maui.Controls.View> object (Android). In both cases, the content is displayed horizontally aligned next to the radio button circle.
|
||||
- When a `ControlTemplate` is applied to a <xref:Microsoft.Maui.Controls.RadioButton>, a <xref:Microsoft.Maui.Controls.View> can be assigned to the `RadioButton.Content` property on all platforms. For more information, see [Redefine RadioButton appearance](#redefine-radiobutton-appearance).
|
||||
- When a <xref:Microsoft.Maui.Controls.ControlTemplate> is applied to a <xref:Microsoft.Maui.Controls.RadioButton>, a <xref:Microsoft.Maui.Controls.View> can be assigned to the `RadioButton.Content` property on all platforms. For more information, see [Redefine RadioButton appearance](#redefine-radiobutton-appearance).
|
||||
|
||||
### Display string-based content
|
||||
|
||||
|
|
@ -108,7 +108,7 @@ In this example, <xref:Microsoft.Maui.Controls.RadioButton> objects are implicit
|
|||
On Android, <xref:Microsoft.Maui.Controls.RadioButton> objects will display a string-based representation of the <xref:Microsoft.Maui.Controls.View> object that's been set as content.
|
||||
|
||||
> [!NOTE]
|
||||
> When a `ControlTemplate` is applied to a <xref:Microsoft.Maui.Controls.RadioButton>, a <xref:Microsoft.Maui.Controls.View> can be assigned to the `RadioButton.Content` property on all platforms. For more information, see [Redefine RadioButton appearance](#redefine-radiobutton-appearance).
|
||||
> When a <xref:Microsoft.Maui.Controls.ControlTemplate> is applied to a <xref:Microsoft.Maui.Controls.RadioButton>, a <xref:Microsoft.Maui.Controls.View> can be assigned to the `RadioButton.Content` property on all platforms. For more information, see [Redefine RadioButton appearance](#redefine-radiobutton-appearance).
|
||||
|
||||
## Associate values with RadioButtons
|
||||
|
||||
|
|
@ -300,9 +300,9 @@ For more information about visual states, see [Visual states](~/user-interface/v
|
|||
|
||||
## Redefine RadioButton appearance
|
||||
|
||||
By default, <xref:Microsoft.Maui.Controls.RadioButton> objects use handlers to utilize native controls on supported platforms. However, <xref:Microsoft.Maui.Controls.RadioButton> visual structure can be redefined with a `ControlTemplate`, so that <xref:Microsoft.Maui.Controls.RadioButton> objects have an identical appearance on all platforms. This is possible because the <xref:Microsoft.Maui.Controls.RadioButton> class inherits from the `TemplatedView` class.
|
||||
By default, <xref:Microsoft.Maui.Controls.RadioButton> objects use handlers to utilize native controls on supported platforms. However, <xref:Microsoft.Maui.Controls.RadioButton> visual structure can be redefined with a <xref:Microsoft.Maui.Controls.ControlTemplate>, so that <xref:Microsoft.Maui.Controls.RadioButton> objects have an identical appearance on all platforms. This is possible because the <xref:Microsoft.Maui.Controls.RadioButton> class inherits from the `TemplatedView` class.
|
||||
|
||||
The following XAML shows a `ControlTemplate` that can be used to redefine the visual structure of <xref:Microsoft.Maui.Controls.RadioButton> objects:
|
||||
The following XAML shows a <xref:Microsoft.Maui.Controls.ControlTemplate> that can be used to redefine the visual structure of <xref:Microsoft.Maui.Controls.RadioButton> objects:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...>
|
||||
|
|
@ -376,12 +376,12 @@ The following XAML shows a `ControlTemplate` that can be used to redefine the vi
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the root element of the `ControlTemplate` is a <xref:Microsoft.Maui.Controls.Border> object that defines `Checked` and `Unchecked` visual states. The <xref:Microsoft.Maui.Controls.Border> object uses a combination of <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Shapes.Ellipse>, and `ContentPresenter` objects to define the visual structure of a <xref:Microsoft.Maui.Controls.RadioButton>. The example also includes an *implicit* style that will assign the `RadioButtonTemplate` to the `ControlTemplate` property of any <xref:Microsoft.Maui.Controls.RadioButton> objects on the page.
|
||||
In this example, the root element of the <xref:Microsoft.Maui.Controls.ControlTemplate> is a <xref:Microsoft.Maui.Controls.Border> object that defines `Checked` and `Unchecked` visual states. The <xref:Microsoft.Maui.Controls.Border> object uses a combination of <xref:Microsoft.Maui.Controls.Grid>, <xref:Microsoft.Maui.Controls.Shapes.Ellipse>, and <xref:Microsoft.Maui.Controls.ContentPresenter> objects to define the visual structure of a <xref:Microsoft.Maui.Controls.RadioButton>. The example also includes an *implicit* style that will assign the `RadioButtonTemplate` to the <xref:Microsoft.Maui.Controls.ControlTemplate> property of any <xref:Microsoft.Maui.Controls.RadioButton> objects on the page.
|
||||
|
||||
> [!NOTE]
|
||||
> The `ContentPresenter` object marks the location in the visual structure where <xref:Microsoft.Maui.Controls.RadioButton> content will be displayed.
|
||||
> The <xref:Microsoft.Maui.Controls.ContentPresenter> object marks the location in the visual structure where <xref:Microsoft.Maui.Controls.RadioButton> content will be displayed.
|
||||
|
||||
The following XAML shows <xref:Microsoft.Maui.Controls.RadioButton> objects that consume the `ControlTemplate` via the *implicit* style:
|
||||
The following XAML shows <xref:Microsoft.Maui.Controls.RadioButton> objects that consume the <xref:Microsoft.Maui.Controls.ControlTemplate> via the *implicit* style:
|
||||
|
||||
```xaml
|
||||
<StackLayout>
|
||||
|
|
@ -440,7 +440,7 @@ The following XAML shows <xref:Microsoft.Maui.Controls.RadioButton> objects that
|
|||
</StackLayout>
|
||||
```
|
||||
|
||||
In this example, the visual structure defined for each <xref:Microsoft.Maui.Controls.RadioButton> is replaced with the visual structure defined in the `ControlTemplate`, and so at runtime the objects in the `ControlTemplate` become part of the visual tree for each <xref:Microsoft.Maui.Controls.RadioButton>. In addition, the content for each <xref:Microsoft.Maui.Controls.RadioButton> is substituted into the `ContentPresenter` defined in the control template. This results in the following <xref:Microsoft.Maui.Controls.RadioButton> appearance:
|
||||
In this example, the visual structure defined for each <xref:Microsoft.Maui.Controls.RadioButton> is replaced with the visual structure defined in the <xref:Microsoft.Maui.Controls.ControlTemplate>, and so at runtime the objects in the <xref:Microsoft.Maui.Controls.ControlTemplate> become part of the visual tree for each <xref:Microsoft.Maui.Controls.RadioButton>. In addition, the content for each <xref:Microsoft.Maui.Controls.RadioButton> is substituted into the <xref:Microsoft.Maui.Controls.ContentPresenter> defined in the control template. This results in the following <xref:Microsoft.Maui.Controls.RadioButton> appearance:
|
||||
|
||||
:::image type="content" source="media/radiobutton/radiobuttons-templated.png" alt-text="Screenshot of templated RadioButtons.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Refresh
|
|||
- `Command`, of type `ICommand`, which is executed when a refresh is triggered.
|
||||
- `CommandParameter`, of type `object`, which is the parameter that's passed to the `Command`.
|
||||
- `IsRefreshing`, of type `bool`, which indicates the current state of the <xref:Microsoft.Maui.Controls.RefreshView>.
|
||||
- `RefreshColor`, of type `Color`, the color of the progress circle that appears during the refresh.
|
||||
- `RefreshColor`, of type <xref:Microsoft.Maui.Graphics.Color>, the color of the progress circle that appears during the refresh.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ scrollView.Content = flexLayout;
|
|||
refreshView.Content = scrollView;
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.RefreshView> provides pull to refresh functionality to a <xref:Microsoft.Maui.Controls.ScrollView> whose child is a <xref:Microsoft.Maui.Controls.FlexLayout>. The <xref:Microsoft.Maui.Controls.FlexLayout> uses a bindable layout to generate its content by binding to a collection of items, and sets the appearance of each item with a `DataTemplate`. For more information about bindable layouts, see [Bindable layout](~/user-interface/layouts/bindablelayout.md).
|
||||
In this example, the <xref:Microsoft.Maui.Controls.RefreshView> provides pull to refresh functionality to a <xref:Microsoft.Maui.Controls.ScrollView> whose child is a <xref:Microsoft.Maui.Controls.FlexLayout>. The <xref:Microsoft.Maui.Controls.FlexLayout> uses a bindable layout to generate its content by binding to a collection of items, and sets the appearance of each item with a <xref:Microsoft.Maui.Controls.DataTemplate>. For more information about bindable layouts, see [Bindable layout](~/user-interface/layouts/bindablelayout.md).
|
||||
|
||||
The value of the `RefreshView.IsRefreshing` property indicates the current state of the <xref:Microsoft.Maui.Controls.RefreshView>. When a refresh is triggered by the user, this property will automatically transition to `true`. Once the refresh completes, you should reset the property to `false`.
|
||||
|
||||
|
|
@ -85,7 +85,7 @@ The following Android screenshot shows a <xref:Microsoft.Maui.Controls.RefreshVi
|
|||
|
||||
:::image type="content" source="media/refreshview/teal-progress-circle.png" alt-text="Screenshot of a RefreshView with a teal progress circle.":::
|
||||
|
||||
In addition, the `BackgroundColor` property can be set to a `Color` that represents the background color of the progress circle.
|
||||
In addition, the `BackgroundColor` property can be set to a <xref:Microsoft.Maui.Graphics.Color> that represents the background color of the progress circle.
|
||||
|
||||
> [!NOTE]
|
||||
> On iOS, the `BackgroundColor` property sets the background color of the `UIView` that contains the progress circle.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ The following XAML example has a <xref:Microsoft.Maui.Controls.ScrollView> as a
|
|||
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ScrollView> has its content set to a <xref:Microsoft.Maui.Controls.StackLayout> that uses a bindable layout to display the `Color` fields defined by .NET MAUI. By default, a <xref:Microsoft.Maui.Controls.ScrollView> scrolls vertically, which reveals more content:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ScrollView> has its content set to a <xref:Microsoft.Maui.Controls.StackLayout> that uses a bindable layout to display the `Colors` fields defined by .NET MAUI. By default, a <xref:Microsoft.Maui.Controls.ScrollView> scrolls vertically, which reveals more content:
|
||||
|
||||
:::image type="content" source="media/scrollview/root-layout.png" alt-text="Screenshot of a root ScrollView layout.":::
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.SearchB
|
|||
|
||||
<xref:Microsoft.Maui.Controls.SearchBar> defines the following properties:
|
||||
|
||||
- `CancelButtonColor` is a `Color` that defines the color of the cancel button.
|
||||
- `CancelButtonColor` is a <xref:Microsoft.Maui.Graphics.Color> that defines the color of the cancel button.
|
||||
- `CharacterSpacing`, is a `double` that's the spacing between characters of the <xref:Microsoft.Maui.Controls.SearchBar> text.
|
||||
- `CursorPosition` is an `int` that determines the position at which the next character will be inserted into the string stored in the `Text` property.
|
||||
- `FontAttributes` is a `FontAttributes` enum value that determines whether the <xref:Microsoft.Maui.Controls.SearchBar> font is bold, italic, or neither.
|
||||
|
|
@ -22,12 +22,12 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.SearchB
|
|||
- `HorizontalTextAlignment` is a `TextAlignment` enum value that defines the horizontal alignment of the query text.
|
||||
- `IsTextPredictionEnabled` is a `bool` that determines whether text prediction and automatic text correction is enabled.
|
||||
- `Placeholder` is a `string` that defines the placeholder text, such as "Search...".
|
||||
- `PlaceholderColor` is a `Color` that defines the color of the placeholder text.
|
||||
- `PlaceholderColor` is a <xref:Microsoft.Maui.Graphics.Color> that defines the color of the placeholder text.
|
||||
- `SearchCommand` is an `ICommand` that allows binding user actions, such as finger taps or clicks, to commands defined on a viewmodel.
|
||||
- `SearchCommandParameter` is an `object` that specifies the parameter that should be passed to the `SearchCommand`.
|
||||
- `SelectionLength` is an `int` that can be used to return or set the length of text selection within the <xref:Microsoft.Maui.Controls.SearchBar>.
|
||||
- `Text` is a `string` containing the query text in the <xref:Microsoft.Maui.Controls.SearchBar>.
|
||||
- `TextColor` is a `Color` that defines the query text color.
|
||||
- `TextColor` is a <xref:Microsoft.Maui.Graphics.Color> that defines the query text color.
|
||||
- `VerticalTextAlignment` is a `TextAlignment` enum value that defines the vertical alignment of the query text.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
|
|
|||
|
|
@ -45,11 +45,11 @@ In this example, the stroke and fill of an <xref:Microsoft.Maui.Controls.Shapes.
|
|||
:::image type="content" source="media/ellipse.png" alt-text="Paint shapes.":::
|
||||
|
||||
> [!IMPORTANT]
|
||||
> <xref:Microsoft.Maui.Controls.Brush> objects use a type converter that enables `Color` values to specified for the <xref:Microsoft.Maui.Controls.Shapes.Shape.Stroke> property.
|
||||
> <xref:Microsoft.Maui.Controls.Brush> objects use a type converter that enables <xref:Microsoft.Maui.Graphics.Color> values to specified for the <xref:Microsoft.Maui.Controls.Shapes.Shape.Stroke> property.
|
||||
|
||||
If you don't specify a <xref:Microsoft.Maui.Controls.Brush> object for <xref:Microsoft.Maui.Controls.Shapes.Shape.Stroke>, or if you set <xref:Microsoft.Maui.Controls.Shapes.Shape.StrokeThickness> to 0, then the border around the shape is not drawn.
|
||||
|
||||
For more information about <xref:Microsoft.Maui.Controls.Brush> objects, see [Brushes](~/user-interface/brushes/index.md). For more information about valid `Color` values, see [Colors](~/user-interface/graphics/colors.md).
|
||||
For more information about <xref:Microsoft.Maui.Controls.Brush> objects, see [Brushes](~/user-interface/brushes/index.md). For more information about valid <xref:Microsoft.Maui.Graphics.Color> values, see [Colors](~/user-interface/graphics/colors.md).
|
||||
|
||||
## Stretch shapes
|
||||
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Slider>
|
|||
- `Minimum`, of type `double`, is the minimum of the range, with a default value of 0.
|
||||
- `Maximum`, of type `double`, is the maximum of the range, with a default value of 1.
|
||||
- `Value`, of type `double`, is the slider's value, which can range between `Minimum` and `Maximum` and has a default value of 0.
|
||||
- `MinimumTrackColor`, of type `Color`, is the bar color on the left side of the thumb.
|
||||
- `MaximumTrackColor`, of type `Color`, is the bar color on the right side of the thumb.
|
||||
- `ThumbColor` of type `Color`, is the thumb color.
|
||||
- `MinimumTrackColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the bar color on the left side of the thumb.
|
||||
- `MaximumTrackColor`, of type <xref:Microsoft.Maui.Graphics.Color>, is the bar color on the right side of the thumb.
|
||||
- `ThumbColor` of type <xref:Microsoft.Maui.Graphics.Color>, is the thumb color.
|
||||
- `ThumbImageSource`, of type `ImageSource`, is the image to use for the thumb, of type `ImageSource`.
|
||||
- `DragStartedCommand`, of type `ICommand`, which is executed at the beginning of a drag action.
|
||||
- `DragCompletedCommand`, of type `ICommand`, which is executed at the end of a drag action.
|
||||
|
|
|
|||
|
|
@ -135,7 +135,7 @@ These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> o
|
|||
|
||||
Each swipe item is defined as a `SwipeItem` object that's placed into one of the four `SwipeItems` directional collections. The `SwipeItem` class derives from the `MenuItem` class, and adds the following members:
|
||||
|
||||
- A `BackgroundColor` property, of type `Color`, that defines the background color of the swipe item. This property is backed by a bindable property.
|
||||
- A `BackgroundColor` property, of type <xref:Microsoft.Maui.Graphics.Color>, that defines the background color of the swipe item. This property is backed by a bindable property.
|
||||
- An `Invoked` event, which is raised when the swipe item is executed.
|
||||
|
||||
> [!IMPORTANT]
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ The following screenshot shows a <xref:Microsoft.Maui.Controls.Switch> control i
|
|||
The <xref:Microsoft.Maui.Controls.Switch> control defines the following properties:
|
||||
|
||||
- `IsToggled` is a `boolean` value that indicates whether the <xref:Microsoft.Maui.Controls.Switch> is on. The default value of this property is `false`.
|
||||
- `OnColor` is a `Color` that affects how the <xref:Microsoft.Maui.Controls.Switch> is rendered in the toggled, or on state.
|
||||
- `ThumbColor` is the `Color` of the switch thumb.
|
||||
- `OnColor` is a <xref:Microsoft.Maui.Graphics.Color> that affects how the <xref:Microsoft.Maui.Controls.Switch> is rendered in the toggled, or on state.
|
||||
- `ThumbColor` is the <xref:Microsoft.Maui.Graphics.Color> of the switch thumb.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means they can be styled and be the target of data bindings.
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ Switch switchControl = new Switch { IsToggled = true };
|
|||
|
||||
## Switch appearance
|
||||
|
||||
In addition to the properties that <xref:Microsoft.Maui.Controls.Switch> inherits from the <xref:Microsoft.Maui.Controls.View> class, <xref:Microsoft.Maui.Controls.Switch> also defines `OnColor` and `ThumbColor` properties. The `OnColor` property can be set to define the <xref:Microsoft.Maui.Controls.Switch> color when it is toggled to its on state, and the `ThumbColor` property can be set to define the `Color` of the switch thumb. The following example shows how to instantiate a <xref:Microsoft.Maui.Controls.Switch> in XAML with these properties set:
|
||||
In addition to the properties that <xref:Microsoft.Maui.Controls.Switch> inherits from the <xref:Microsoft.Maui.Controls.View> class, <xref:Microsoft.Maui.Controls.Switch> also defines `OnColor` and `ThumbColor` properties. The `OnColor` property can be set to define the <xref:Microsoft.Maui.Controls.Switch> color when it is toggled to its on state, and the `ThumbColor` property can be set to define the <xref:Microsoft.Maui.Graphics.Color> of the switch thumb. The following example shows how to instantiate a <xref:Microsoft.Maui.Controls.Switch> in XAML with these properties set:
|
||||
|
||||
```xaml
|
||||
<Switch OnColor="Orange"
|
||||
|
|
|
|||
|
|
@ -75,9 +75,9 @@ Each item in a <xref:Microsoft.Maui.Controls.TableView> is defined by a <xref:Mi
|
|||
A <xref:Microsoft.Maui.Controls.TextCell> displays primary and secondary text on separate lines. <xref:Microsoft.Maui.Controls.TextCell> defines the following properties:
|
||||
|
||||
- `Text`, of type `string`, defines the primary text to be displayed.
|
||||
- `TextColor`, of type `Color`, represents the color of the primary text.
|
||||
- `TextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, represents the color of the primary text.
|
||||
- `Detail`, of type `string`, defines the secondary text to be displayed.
|
||||
- `DetailColor`, of type `Color`, indicates the color of the secondary text.
|
||||
- `DetailColor`, of type <xref:Microsoft.Maui.Graphics.Color>, indicates the color of the secondary text.
|
||||
- `Command`, of type `ICommand`, defines the command that's executed when the cell is tapped.
|
||||
- `CommandParameter`, of type `object`, represents the parameter that's passed to the command.
|
||||
|
||||
|
|
@ -145,7 +145,7 @@ A <xref:Microsoft.Maui.Controls.SwitchCell> displays text and a switch that can
|
|||
|
||||
- `Text`, of type `string`, defines the text to display next to the switch.
|
||||
- `On`, of type `bool`, represents whether the switch is on or off.
|
||||
- `OnColor`, of type `Color`, indicates the color of the switch when in it's on position.
|
||||
- `OnColor`, of type <xref:Microsoft.Maui.Graphics.Color>, indicates the color of the switch when in it's on position.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
|
|
@ -177,7 +177,7 @@ An <xref:Microsoft.Maui.Controls.EntryCell> displays a label and text data that'
|
|||
- `HorizontalTextAlignment`, of type `TextAlignment`, represents the horizontal alignment of the text.
|
||||
- `Keyboard`, of type `Keyboard`, determines the keyboard to display when entering text.
|
||||
- <xref:Microsoft.Maui.Controls.Label>, of type `string`, represents the text to display to the left of the editable text.
|
||||
- `LabelColor`, of type `Color`, defines the color of the label text.
|
||||
- `LabelColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the color of the label text.
|
||||
- `Placeholder`, of type `string`, represents the text that's displayed when the `Text` property is empty.
|
||||
- `Text`, of type `string`, defines the text that's editable.
|
||||
- `VerticalTextAlignment`, of type `TextAlignment`, represents the vertical alignment of the text.
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.TimePic
|
|||
|
||||
- `Time` of type `TimeSpan`, the selected time, which defaults to a `TimeSpan` of 0. The `TimeSpan` type indicates a duration of time since midnight.
|
||||
- `Format` of type `string`, a [standard](/dotnet/standard/base-types/standard-date-and-time-format-strings/) or [custom](/dotnet/standard/base-types/custom-date-and-time-format-strings/) .NET formatting string, which defaults to "t", the short time pattern.
|
||||
- `TextColor` of type `Color`, the color used to display the selected time.
|
||||
- `TextColor` of type <xref:Microsoft.Maui.Graphics.Color>, the color used to display the selected time.
|
||||
- `FontAttributes` of type `FontAttributes`, which defaults to `FontAtributes.None`.
|
||||
- `FontFamily` of type `string`, which defaults to `null`.
|
||||
- `FontSize` of type `double`, which defaults to -1.0.
|
||||
|
|
|
|||
|
|
@ -205,7 +205,7 @@ Font icons can be displayed by .NET MAUI apps by specifying the font icon data i
|
|||
- `Glyph` – the unicode character value of the font icon, specified as a `string`.
|
||||
- `Size` – a `double` value that indicates the size, in device-independent units, of the rendered font icon. The default value is 30. In addition, this property can be set to a named font size.
|
||||
- `FontFamily` – a `string` representing the font family to which the font icon belongs.
|
||||
- `Color` – an optional `Color` value to be used when displaying the font icon.
|
||||
- `Color` – an optional <xref:Microsoft.Maui.Graphics.Color> value to be used when displaying the font icon.
|
||||
|
||||
This data is used to create a PNG, which can be displayed by any view that can display an `ImageSource`. This approach permits font icons, such as emojis, to be displayed by multiple views, as opposed to limiting font icon display to a single text presenting view, such as a <xref:Microsoft.Maui.Controls.Label>.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,13 +8,13 @@ ms.date: 02/22/2022
|
|||
|
||||
[ Browse the sample](/samples/dotnet/maui-samples/userinterface-bindablelayout)
|
||||
|
||||
.NET Multi-platform App UI (.NET MAUI) bindable layouts enable any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class to generate its content by binding to a collection of items, with the option to set the appearance of each item with a `DataTemplate`.
|
||||
.NET Multi-platform App UI (.NET MAUI) bindable layouts enable any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class to generate its content by binding to a collection of items, with the option to set the appearance of each item with a <xref:Microsoft.Maui.Controls.DataTemplate>.
|
||||
|
||||
Bindable layouts are provided by the <xref:Microsoft.Maui.Controls.BindableLayout> class, which exposes the following attached properties:
|
||||
|
||||
- `ItemsSource` – specifies the collection of `IEnumerable` items to be displayed by the layout.
|
||||
- `ItemTemplate` – specifies the `DataTemplate` to apply to each item in the collection of items displayed by the layout.
|
||||
- `ItemTemplateSelector` – specifies the `DataTemplateSelector` that will be used to choose a `DataTemplate` for an item at runtime.
|
||||
- `ItemTemplate` – specifies the <xref:Microsoft.Maui.Controls.DataTemplate> to apply to each item in the collection of items displayed by the layout.
|
||||
- `ItemTemplateSelector` – specifies the <xref:Microsoft.Maui.Controls.DataTemplateSelector> that will be used to choose a <xref:Microsoft.Maui.Controls.DataTemplate> for an item at runtime.
|
||||
|
||||
> [!NOTE]
|
||||
> The `ItemTemplate` property takes precedence when both the `ItemTemplate` and `ItemTemplateSelector` properties are set.
|
||||
|
|
@ -22,7 +22,7 @@ Bindable layouts are provided by the <xref:Microsoft.Maui.Controls.BindableLayou
|
|||
In addition, the <xref:Microsoft.Maui.Controls.BindableLayout> class exposes the following bindable properties:
|
||||
|
||||
- `EmptyView` – specifies the `string` or view that will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The default value is `null`.
|
||||
- `EmptyViewTemplate` – specifies the `DataTemplate` that will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The default value is `null`.
|
||||
- `EmptyViewTemplate` – specifies the <xref:Microsoft.Maui.Controls.DataTemplate> that will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The default value is `null`.
|
||||
|
||||
> [!NOTE]
|
||||
> The `EmptyViewTemplate` property takes precedence when both the `EmptyView` and `EmptyViewTemplate` properties are set.
|
||||
|
|
@ -34,7 +34,7 @@ When the `BinableLayout.ItemsSource` property is set to a collection of items an
|
|||
Bindable layouts should only be used when the collection of items to be displayed is small, and scrolling and selection isn't required. While scrolling can be provided by wrapping a bindable layout in a <xref:Microsoft.Maui.Controls.ScrollView>, this is not recommended as bindable layouts lack UI virtualization. When scrolling is required, a scrollable view that includes UI virtualization, such as <xref:Microsoft.Maui.Controls.ListView> or <xref:Microsoft.Maui.Controls.CollectionView>, should be used. Failure to observe this recommendation can lead to performance issues.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> While it's technically possible to attach a bindable layout to any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class, it's not always practical to do so, particularly for the <xref:Microsoft.Maui.Controls.AbsoluteLayout> and <xref:Microsoft.Maui.Controls.Grid> classes. For example, consider the scenario of wanting to display a collection of data in a <xref:Microsoft.Maui.Controls.Grid> using a bindable layout, where each item in the collection is an object containing multiple properties. Each row in the <xref:Microsoft.Maui.Controls.Grid> should display an object from the collection, with each column in the <xref:Microsoft.Maui.Controls.Grid> displaying one of the object's properties. Because the `DataTemplate` for the bindable layout can only contain a single object, it's necessary for that object to be a layout class containing multiple views that each display one of the object's properties in a specific <xref:Microsoft.Maui.Controls.Grid> column. While this scenario can be realised with bindable layouts, it results in a parent <xref:Microsoft.Maui.Controls.Grid> containing a child <xref:Microsoft.Maui.Controls.Grid> for each item in the bound collection, which is a highly inefficient and problematic use of the <xref:Microsoft.Maui.Controls.Grid> layout.
|
||||
> While it's technically possible to attach a bindable layout to any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class, it's not always practical to do so, particularly for the <xref:Microsoft.Maui.Controls.AbsoluteLayout> and <xref:Microsoft.Maui.Controls.Grid> classes. For example, consider the scenario of wanting to display a collection of data in a <xref:Microsoft.Maui.Controls.Grid> using a bindable layout, where each item in the collection is an object containing multiple properties. Each row in the <xref:Microsoft.Maui.Controls.Grid> should display an object from the collection, with each column in the <xref:Microsoft.Maui.Controls.Grid> displaying one of the object's properties. Because the <xref:Microsoft.Maui.Controls.DataTemplate> for the bindable layout can only contain a single object, it's necessary for that object to be a layout class containing multiple views that each display one of the object's properties in a specific <xref:Microsoft.Maui.Controls.Grid> column. While this scenario can be realised with bindable layouts, it results in a parent <xref:Microsoft.Maui.Controls.Grid> containing a child <xref:Microsoft.Maui.Controls.Grid> for each item in the bound collection, which is a highly inefficient and problematic use of the <xref:Microsoft.Maui.Controls.Grid> layout.
|
||||
|
||||
## Populate a bindable layout with data
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ When the `BindableLayout.ItemsSource` attached property is set on a layout, but
|
|||
|
||||
## Define item appearance
|
||||
|
||||
The appearance of each item in the bindable layout can be defined by setting the `BindableLayout.ItemTemplate` attached property to a `DataTemplate`:
|
||||
The appearance of each item in the bindable layout can be defined by setting the `BindableLayout.ItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<StackLayout BindableLayout.ItemsSource="{Binding User.TopFollowers}"
|
||||
|
|
@ -83,7 +83,7 @@ BindableLayout.SetItemsSource(stackLayout, viewModel.User.TopFollowers);
|
|||
BindableLayout.SetItemTemplate(stackLayout, imageTemplate);
|
||||
```
|
||||
|
||||
In this example, every item in the `TopFollowers` collection will be displayed by an <xref:Microsoft.Maui.Controls.Image> view defined in the `DataTemplate`:
|
||||
In this example, every item in the `TopFollowers` collection will be displayed by an <xref:Microsoft.Maui.Controls.Image> view defined in the <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
:::image type="content" source="media/bindablelayout/top-followers.png" alt-text=".NET MAUI bindable layout with a DataTemplate.":::
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ For more information about data templates, see [Data templates](~/fundamentals/d
|
|||
|
||||
## Choose item appearance at runtime
|
||||
|
||||
The appearance of each item in the bindable layout can be chosen at runtime, based on the item value, by setting the `BindableLayout.ItemTemplateSelector` attached property to a `DataTemplateSelector`:
|
||||
The appearance of each item in the bindable layout can be chosen at runtime, based on the item value, by setting the `BindableLayout.ItemTemplateSelector` attached property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector>:
|
||||
|
||||
```xaml
|
||||
<FlexLayout BindableLayout.ItemsSource="{Binding User.FavoriteTech}"
|
||||
|
|
@ -123,7 +123,7 @@ public class TechItemTemplateSelector : DataTemplateSelector
|
|||
}
|
||||
```
|
||||
|
||||
The `TechItemTemplateSelector` class defines `DefaultTemplate` and `MAUITemplate` `DataTemplate` properties that are set to different data templates. The `OnSelectTemplate` method returns the `MAUITemplate`, which displays an item in dark red with a heart next to it, when the item is equal to ".NET MAUI". When the item isn't equal to ".NET MAUI", the `OnSelectTemplate` method returns the `DefaultTemplate`, which displays an item using the default color of a <xref:Microsoft.Maui.Controls.Label>:
|
||||
The `TechItemTemplateSelector` class defines `DefaultTemplate` and `MAUITemplate` <xref:Microsoft.Maui.Controls.DataTemplate> properties that are set to different data templates. The `OnSelectTemplate` method returns the `MAUITemplate`, which displays an item in dark red with a heart next to it, when the item is equal to ".NET MAUI". When the item isn't equal to ".NET MAUI", the `OnSelectTemplate` method returns the `DefaultTemplate`, which displays an item using the default color of a <xref:Microsoft.Maui.Controls.Label>:
|
||||
|
||||
:::image type="content" source="media/bindablelayout/favorite-tech.png" alt-text=".NET MAUI bindable layout with a DataTemplateSelector.":::
|
||||
|
||||
|
|
@ -168,7 +168,7 @@ The result is that when the data bound collection is `null`, the <xref:Microsoft
|
|||
|
||||
:::image type="content" source="media/bindablelayout/emptyview-views.png" alt-text="Screenshot of a bindable layout empty view with multiple views.":::
|
||||
|
||||
Similarly, the `EmptyViewTemplate` can be set to a `DataTemplate`, which will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The `DataTemplate` can contain a single view, or a view that contains multiple child views. In addition, the `BindingContext` of the `EmptyViewTemplate` will be inherited from the `BindingContext` of the <xref:Microsoft.Maui.Controls.BindableLayout>. The following XAML example shows the `EmptyViewTemplate` property set to a `DataTemplate` that contains a single view:
|
||||
Similarly, the `EmptyViewTemplate` can be set to a <xref:Microsoft.Maui.Controls.DataTemplate>, which will be displayed when the `ItemsSource` property is `null`, or when the collection specified by the `ItemsSource` property is `null` or empty. The <xref:Microsoft.Maui.Controls.DataTemplate> can contain a single view, or a view that contains multiple child views. In addition, the `BindingContext` of the `EmptyViewTemplate` will be inherited from the `BindingContext` of the <xref:Microsoft.Maui.Controls.BindableLayout>. The following XAML example shows the `EmptyViewTemplate` property set to a <xref:Microsoft.Maui.Controls.DataTemplate> that contains a single view:
|
||||
|
||||
```xaml
|
||||
<StackLayout BindableLayout.ItemsSource="{Binding UserWithoutAchievements.Achievements}">
|
||||
|
|
@ -181,12 +181,12 @@ Similarly, the `EmptyViewTemplate` can be set to a `DataTemplate`, which will be
|
|||
</StackLayout>
|
||||
```
|
||||
|
||||
The result is that when the data bound collection is `null`, the <xref:Microsoft.Maui.Controls.Label> in the `DataTemplate` is displayed:
|
||||
The result is that when the data bound collection is `null`, the <xref:Microsoft.Maui.Controls.Label> in the <xref:Microsoft.Maui.Controls.DataTemplate> is displayed:
|
||||
|
||||
:::image type="content" source="media/bindablelayout/emptyviewtemplate.png" alt-text="Screenshot of a bindable layout empty view template.":::
|
||||
|
||||
> [!NOTE]
|
||||
> The `EmptyViewTemplate` property can't be set via a `DataTemplateSelector`.
|
||||
> The `EmptyViewTemplate` property can't be set via a <xref:Microsoft.Maui.Controls.DataTemplateSelector>.
|
||||
|
||||
## Choose an EmptyView at runtime
|
||||
|
||||
|
|
|
|||
|
|
@ -256,11 +256,11 @@ For more information, see [RelativeLayout](relativelayout.md). -->
|
|||
|
||||
## BindableLayout
|
||||
|
||||
A <xref:Microsoft.Maui.Controls.BindableLayout> enables any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class to generate its content by binding to a collection of items, with the option to set the appearance of each item with a `DataTemplate`.
|
||||
A <xref:Microsoft.Maui.Controls.BindableLayout> enables any layout class that derives from the <xref:Microsoft.Maui.Controls.Layout> class to generate its content by binding to a collection of items, with the option to set the appearance of each item with a <xref:Microsoft.Maui.Controls.DataTemplate>.
|
||||
|
||||
A bindable layout is populated with data by setting its `ItemsSource` property to any collection that implements `IEnumerable`, and attaching it to a <xref:Microsoft.Maui.Controls.Layout>-derived class. The appearance of each item in the bindable layout can be defined by setting the `BindableLayout.ItemTemplate` attached property to a `DataTemplate`.
|
||||
A bindable layout is populated with data by setting its `ItemsSource` property to any collection that implements `IEnumerable`, and attaching it to a <xref:Microsoft.Maui.Controls.Layout>-derived class. The appearance of each item in the bindable layout can be defined by setting the `BindableLayout.ItemTemplate` attached property to a <xref:Microsoft.Maui.Controls.DataTemplate>.
|
||||
|
||||
The following XAML shows how to bind a <xref:Microsoft.Maui.Controls.StackLayout> to a collection of items, and define their appearance with a `DataTemplate`:
|
||||
The following XAML shows how to bind a <xref:Microsoft.Maui.Controls.StackLayout> to a collection of items, and define their appearance with a <xref:Microsoft.Maui.Controls.DataTemplate>:
|
||||
|
||||
```xaml
|
||||
<StackLayout BindableLayout.ItemsSource="{Binding User.TopFollowers}"
|
||||
|
|
|
|||
|
|
@ -119,7 +119,7 @@ public class FlyoutPageItem
|
|||
}
|
||||
```
|
||||
|
||||
A `DataTemplate` is assigned to the `CollectionView.ItemTemplate` property, to display each `FlyoutPageItem`. The `DataTemplate` contains a <xref:Microsoft.Maui.Controls.Grid> that consists of an <xref:Microsoft.Maui.Controls.Image> and a <xref:Microsoft.Maui.Controls.Label>. The <xref:Microsoft.Maui.Controls.Image> displays the `IconSource` property value, and the <xref:Microsoft.Maui.Controls.Label> displays the `Title` property value, for each `FlyoutPageItem`. In addition, the flyout page has its `Title` and `IconImageSource` properties set. The icon will appear on the detail page, provided that the detail page has a title bar.
|
||||
A <xref:Microsoft.Maui.Controls.DataTemplate> is assigned to the `CollectionView.ItemTemplate` property, to display each `FlyoutPageItem`. The <xref:Microsoft.Maui.Controls.DataTemplate> contains a <xref:Microsoft.Maui.Controls.Grid> that consists of an <xref:Microsoft.Maui.Controls.Image> and a <xref:Microsoft.Maui.Controls.Label>. The <xref:Microsoft.Maui.Controls.Image> displays the `IconSource` property value, and the <xref:Microsoft.Maui.Controls.Label> displays the `Title` property value, for each `FlyoutPageItem`. In addition, the flyout page has its `Title` and `IconImageSource` properties set. The icon will appear on the detail page, provided that the detail page has a title bar.
|
||||
|
||||
> [!NOTE]
|
||||
> The `Flyout` page must have its `Title` property set, or an exception will occur.
|
||||
|
|
|
|||
|
|
@ -13,13 +13,13 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.Navigat
|
|||
<xref:Microsoft.Maui.Controls.NavigationPage> defines the following properties:
|
||||
|
||||
- `BarBackground`, of type <xref:Microsoft.Maui.Controls.Brush>, specifies the background of the navigation bar as a <xref:Microsoft.Maui.Controls.Brush>.
|
||||
- `BarBackgroundColor`, of type `Color`, specifies the background color of the navigation bar.
|
||||
- `BarBackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, specifies the background color of the navigation bar.
|
||||
- `BackButtonTitle`, of type `string`, represents the text to use for the back button. This is an attached property.
|
||||
- `BarTextColor`, of type `Color`, specifies the color of the text on the navigation bar.
|
||||
- `BarTextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, specifies the color of the text on the navigation bar.
|
||||
- `CurrentPage`, of type <xref:Microsoft.Maui.Controls.Page>, represents the page that's on top of the navigation stack. This is a read-only property.
|
||||
- `HasNavigationBar`, of type `bool`, represents whether a navigation bar is present on the <xref:Microsoft.Maui.Controls.NavigationPage>. The default value of this property is `true`. This is an attached property.
|
||||
- `HasBackButton`, of type `bool`, represents whether the navigation bar includes a back button. The default value of this property is `true`. This is an attached property.
|
||||
- `IconColor`, of type `Color`, defines the background color of the icon in the navigation bar. This is an attached property.
|
||||
- `IconColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the background color of the icon in the navigation bar. This is an attached property.
|
||||
- `RootPage`, of type <xref:Microsoft.Maui.Controls.Page>, represents the root page of the navigation stack. This is a read-only property.
|
||||
- `TitleIconImageSource`, of type `ImageSource`, defines the icon that represents the title on the navigation bar. This is an attached property.
|
||||
- `TitleView`, of type <xref:Microsoft.Maui.Controls.View>, defines the view that can be displayed in the navigation bar. This is an attached property.
|
||||
|
|
|
|||
|
|
@ -13,10 +13,10 @@ The .NET Multi-platform App UI (.NET MAUI) <xref:Microsoft.Maui.Controls.TabbedP
|
|||
<xref:Microsoft.Maui.Controls.TabbedPage> defines the following properties:
|
||||
|
||||
- `BarBackground`, of type <xref:Microsoft.Maui.Controls.Brush>, defines the background of the tab bar.
|
||||
- `BarBackgroundColor`, of type `Color`, defines the background color of the tab bar.
|
||||
- `BarTextColor`, of type `Color`, represents the color of the text on the tab bar.
|
||||
- `SelectedTabColor`, of type `Color`, indicates the color of a tab when it's selected.
|
||||
- `UnselectedTabColor`, of type `Color`, represents the color of a tab when it's unselected.
|
||||
- `BarBackgroundColor`, of type <xref:Microsoft.Maui.Graphics.Color>, defines the background color of the tab bar.
|
||||
- `BarTextColor`, of type <xref:Microsoft.Maui.Graphics.Color>, represents the color of the text on the tab bar.
|
||||
- `SelectedTabColor`, of type <xref:Microsoft.Maui.Graphics.Color>, indicates the color of a tab when it's selected.
|
||||
- `UnselectedTabColor`, of type <xref:Microsoft.Maui.Graphics.Color>, represents the color of a tab when it's unselected.
|
||||
|
||||
These properties are backed by <xref:Microsoft.Maui.Controls.BindableProperty> objects, which means that they can be targets of data bindings, and styled.
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ In a <xref:Microsoft.Maui.Controls.TabbedPage>, each <xref:Microsoft.Maui.Contro
|
|||
Two approaches can be used to create a <xref:Microsoft.Maui.Controls.TabbedPage>:
|
||||
|
||||
- Populate the <xref:Microsoft.Maui.Controls.TabbedPage> with a collection of child <xref:Microsoft.Maui.Controls.Page> objects, such as a collection of <xref:Microsoft.Maui.Controls.ContentPage> objects. For more information, see [Populate a TabbedPage with a Page collection](#populate-a-tabbedpage-with-a-page-collection).
|
||||
- Assign a collection to the `ItemsSource` property and assign a `DataTemplate` to the `ItemTemplate` property to return pages for objects in the collection. For more information, see [Populate a TabbedPage with a DataTemplate](#populate-a-tabbedpage-with-a-datatemplate).
|
||||
- Assign a collection to the `ItemsSource` property and assign a <xref:Microsoft.Maui.Controls.DataTemplate> to the `ItemTemplate` property to return pages for objects in the collection. For more information, see [Populate a TabbedPage with a DataTemplate](#populate-a-tabbedpage-with-a-datatemplate).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> A <xref:Microsoft.Maui.Controls.TabbedPage> should only be populated with <xref:Microsoft.Maui.Controls.NavigationPage> and <xref:Microsoft.Maui.Controls.ContentPage> objects.
|
||||
|
|
@ -68,7 +68,7 @@ The page content for a tab appears when the tab is selected.
|
|||
|
||||
### Populate a TabbedPage with a DataTemplate
|
||||
|
||||
<xref:Microsoft.Maui.Controls.TabbedPage> inherits `ItemsSource`, `ItemTemplate`, and `SelectedItem` bindable properties from the `MultiPage<T>` class. These properties enable you to generate <xref:Microsoft.Maui.Controls.TabbedPage> children dynamically, by setting the `ItemsSource` property to an `IEnumerable` collection of objects with public properties suitable for data bindings, and by setting the `ItemTemplate` property to a `DataTemplate` with a page type as the root element.
|
||||
<xref:Microsoft.Maui.Controls.TabbedPage> inherits `ItemsSource`, `ItemTemplate`, and `SelectedItem` bindable properties from the `MultiPage<T>` class. These properties enable you to generate <xref:Microsoft.Maui.Controls.TabbedPage> children dynamically, by setting the `ItemsSource` property to an `IEnumerable` collection of objects with public properties suitable for data bindings, and by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate> with a page type as the root element.
|
||||
|
||||
The following example shows generating <xref:Microsoft.Maui.Controls.TabbedPage> children dynamically:
|
||||
|
||||
|
|
|
|||
|
|
@ -112,7 +112,7 @@ The following example shows *explicit* styles in a page's <xref:Microsoft.Maui.C
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> defines three styles that are explicitly set on the page's <xref:Microsoft.Maui.Controls.Label> objects. Each <xref:Microsoft.Maui.Controls.Style> is used to display text in a different color, while also setting the font size, and horizontal and vertical layout options. Each <xref:Microsoft.Maui.Controls.Style> is applied to a different <xref:Microsoft.Maui.Controls.Label> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> properties using the `StaticResource` markup extension. In addition, while the final <xref:Microsoft.Maui.Controls.Label> has a <xref:Microsoft.Maui.Controls.Style> set on it, it also overrides the `TextColor` property to a different `Color` value.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> defines three styles that are explicitly set on the page's <xref:Microsoft.Maui.Controls.Label> objects. Each <xref:Microsoft.Maui.Controls.Style> is used to display text in a different color, while also setting the font size, and horizontal and vertical layout options. Each <xref:Microsoft.Maui.Controls.Style> is applied to a different <xref:Microsoft.Maui.Controls.Label> by setting its <xref:Microsoft.Maui.Controls.NavigableElement.Style> properties using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension. In addition, while the final <xref:Microsoft.Maui.Controls.Label> has a <xref:Microsoft.Maui.Controls.Style> set on it, it also overrides the `TextColor` property to a different <xref:Microsoft.Maui.Graphics.Color> value.
|
||||
|
||||
## Implicit styles
|
||||
|
||||
|
|
@ -143,7 +143,7 @@ The following code example shows an *implicit* style in a page's <xref:Microsoft
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> defines a single *implicit* style that are implicitly set on the page's <xref:Microsoft.Maui.Controls.Entry> objects. The <xref:Microsoft.Maui.Controls.Style> is used to display blue text on a yellow background, while also setting other appearance options. The <xref:Microsoft.Maui.Controls.Style> is added to the page's <xref:Microsoft.Maui.Controls.ResourceDictionary> without specifying an `x:Key` attribute. Therefore, the <xref:Microsoft.Maui.Controls.Style> is applied to all the <xref:Microsoft.Maui.Controls.Entry> objects implicitly as they match the `TargetType` property of the <xref:Microsoft.Maui.Controls.Style> exactly. However, the <xref:Microsoft.Maui.Controls.Style> is not applied to the `CustomEntry` object, which is a subclassed <xref:Microsoft.Maui.Controls.Entry>. In addition, the fourth <xref:Microsoft.Maui.Controls.Entry> overrides the `BackgroundColor` and `TextColor` properties of the style to different `Color` values.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.ResourceDictionary> defines a single *implicit* style that are implicitly set on the page's <xref:Microsoft.Maui.Controls.Entry> objects. The <xref:Microsoft.Maui.Controls.Style> is used to display blue text on a yellow background, while also setting other appearance options. The <xref:Microsoft.Maui.Controls.Style> is added to the page's <xref:Microsoft.Maui.Controls.ResourceDictionary> without specifying an `x:Key` attribute. Therefore, the <xref:Microsoft.Maui.Controls.Style> is applied to all the <xref:Microsoft.Maui.Controls.Entry> objects implicitly as they match the `TargetType` property of the <xref:Microsoft.Maui.Controls.Style> exactly. However, the <xref:Microsoft.Maui.Controls.Style> is not applied to the `CustomEntry` object, which is a subclassed <xref:Microsoft.Maui.Controls.Entry>. In addition, the fourth <xref:Microsoft.Maui.Controls.Entry> overrides the `BackgroundColor` and `TextColor` properties of the style to different <xref:Microsoft.Maui.Graphics.Color> values.
|
||||
|
||||
## Apply a style to derived types
|
||||
|
||||
|
|
@ -216,7 +216,7 @@ The following example shows a page consuming the `buttonStyle` on the page's <xr
|
|||
|
||||
## Style inheritance
|
||||
|
||||
Styles can inherit from other styles to reduce duplication and enable reuse. This is achieved by setting the `Style.BasedOn` property to an existing <xref:Microsoft.Maui.Controls.Style>. In XAML, this can be achieved by setting the `BasedOn` property to a `StaticResource` markup extension that references a previously created <xref:Microsoft.Maui.Controls.Style>.
|
||||
Styles can inherit from other styles to reduce duplication and enable reuse. This is achieved by setting the `Style.BasedOn` property to an existing <xref:Microsoft.Maui.Controls.Style>. In XAML, this can be achieved by setting the `BasedOn` property to a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension that references a previously created <xref:Microsoft.Maui.Controls.Style>.
|
||||
|
||||
Styles that inherit from a base style can include <xref:Microsoft.Maui.Controls.Setter> instances for new properties, or use them to override setters from the base style. In addition, styles that inherit from a base style must target the same type, or a type that derives from the type targeted by the base style. For example, if a base style targets <xref:Microsoft.Maui.Controls.View> objects, styles that are based on the base style can target <xref:Microsoft.Maui.Controls.View> objects or types that derive from the <xref:Microsoft.Maui.Controls.View> class, such as <xref:Microsoft.Maui.Controls.Label> and <xref:Microsoft.Maui.Controls.Button> objects.
|
||||
|
||||
|
|
@ -273,7 +273,7 @@ In this example, the `baseStyle` targets <xref:Microsoft.Maui.Controls.View> obj
|
|||
|
||||
Styles do not respond to property changes, and remain unchanged for the duration of an app. For example, after assigning a <xref:Microsoft.Maui.Controls.Style> to a visual element, if one of the <xref:Microsoft.Maui.Controls.Setter> objects is modified, removed, or a new <xref:Microsoft.Maui.Controls.Setter> added, the changes won't be applied to the visual element. However, apps can respond to style changes dynamically at runtime by using dynamic resources.
|
||||
|
||||
The `DynamicResource` markup extension is similar to the `StaticResource` markup extension in that both use a dictionary key to fetch a value from a <xref:Microsoft.Maui.Controls.ResourceDictionary>. However, while the `StaticResource` performs a single dictionary lookup, the `DynamicResource` maintains a link to the dictionary key. Therefore, if the dictionary entry associated with the key is replaced, the change is applied to the visual element. This enables runtime style changes to be made in an app.
|
||||
The [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension is similar to the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension in that both use a dictionary key to fetch a value from a <xref:Microsoft.Maui.Controls.ResourceDictionary>. However, while the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) performs a single dictionary lookup, the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) maintains a link to the dictionary key. Therefore, if the dictionary entry associated with the key is replaced, the change is applied to the visual element. This enables runtime style changes to be made in an app.
|
||||
|
||||
The following example shows *dynamic* styles:
|
||||
|
||||
|
|
@ -303,7 +303,7 @@ The following example shows *dynamic* styles:
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.SearchBar> object use the `DynamicResource` markup extension to set a <xref:Microsoft.Maui.Controls.Style> named `blueSearchBarStyle`. The <xref:Microsoft.Maui.Controls.SearchBar> can then have its <xref:Microsoft.Maui.Controls.Style> definition updated in code:
|
||||
In this example, the <xref:Microsoft.Maui.Controls.SearchBar> object use the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension to set a <xref:Microsoft.Maui.Controls.Style> named `blueSearchBarStyle`. The <xref:Microsoft.Maui.Controls.SearchBar> can then have its <xref:Microsoft.Maui.Controls.Style> definition updated in code:
|
||||
|
||||
```csharp
|
||||
Resources["blueSearchBarStyle"] = Resources["greenSearchBarStyle"];
|
||||
|
|
@ -349,7 +349,7 @@ The following example shows *dynamic* style inheritance:
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, the <xref:Microsoft.Maui.Controls.SearchBar> object uses the `StaticResource` markup extension to reference a <xref:Microsoft.Maui.Controls.Style> named `tealSearchBarStyle`. This <xref:Microsoft.Maui.Controls.Style> sets some additional properties and uses the `BaseResourceKey` property to reference `blueSearchBarStyle`. The `DynamicResource` markup extension is not required because `tealSearchBarStyle` will not change, except for the <xref:Microsoft.Maui.Controls.Style> it derives from. Therefore, `tealSearchBarStyle` maintains a link to `blueSearchBarStyle` and is updated when the base style changes.
|
||||
In this example, the <xref:Microsoft.Maui.Controls.SearchBar> object uses the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension to reference a <xref:Microsoft.Maui.Controls.Style> named `tealSearchBarStyle`. This <xref:Microsoft.Maui.Controls.Style> sets some additional properties and uses the `BaseResourceKey` property to reference `blueSearchBarStyle`. The [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension is not required because `tealSearchBarStyle` will not change, except for the <xref:Microsoft.Maui.Controls.Style> it derives from. Therefore, `tealSearchBarStyle` maintains a link to `blueSearchBarStyle` and is updated when the base style changes.
|
||||
|
||||
The `blueSearchBarStyle` definition can be updated in code:
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ The `AppThemeBinding` markup extension enables you to consume a resource, such a
|
|||
|
||||
In this example, the text color of the first <xref:Microsoft.Maui.Controls.Label> is set to green when the device is using its light theme, and is set to red when the device is using its dark theme. Similarly, the <xref:Microsoft.Maui.Controls.Image> displays a different image file based upon the current system theme.
|
||||
|
||||
In addition, resources defined in a <xref:Microsoft.Maui.Controls.ResourceDictionary> can be consumed with the `StaticResource` markup extension:
|
||||
In addition, resources defined in a <xref:Microsoft.Maui.Controls.ResourceDictionary> can be consumed with the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension:
|
||||
|
||||
```xaml
|
||||
<ContentPage ...>
|
||||
|
|
@ -78,7 +78,7 @@ For more information about the `AppThemeBinding` markup extension, see [AppTheme
|
|||
|
||||
.NET MAUI includes `SetAppThemeColor` and `SetAppTheme<T>` extension methods that enable <xref:Microsoft.Maui.Controls.VisualElement> objects to respond to system theme changes.
|
||||
|
||||
The `SetAppThemeColor` method enables `Color` objects to be specified that will be set on a target property based on the current system theme:
|
||||
The `SetAppThemeColor` method enables <xref:Microsoft.Maui.Graphics.Color> objects to be specified that will be set on a target property based on the current system theme:
|
||||
|
||||
```csharp
|
||||
Label label = new Label();
|
||||
|
|
|
|||
|
|
@ -8,17 +8,17 @@ ms.date: 02/25/2022
|
|||
|
||||
[ Browse the sample](/samples/dotnet/maui-samples/userinterface-theming)
|
||||
|
||||
.NET Multi-platform App UI (.NET MAUI) apps can respond to style changes dynamically at runtime by using the `DynamicResource` markup extension. This markup extension is similar to the `StaticResource` markup extension, in that both use a dictionary key to fetch a value from a <xref:Microsoft.Maui.Controls.ResourceDictionary>. However, while the `StaticResource` markup extension performs a single dictionary lookup, the `DynamicResource` markup extension maintains a link to the dictionary key. Therefore, if the value associated with the key is replaced, the change is applied to the <xref:Microsoft.Maui.Controls.VisualElement>. This enables runtime theming to be implemented in .NET MAUI apps.
|
||||
.NET Multi-platform App UI (.NET MAUI) apps can respond to style changes dynamically at runtime by using the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension. This markup extension is similar to the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension, in that both use a dictionary key to fetch a value from a <xref:Microsoft.Maui.Controls.ResourceDictionary>. However, while the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension performs a single dictionary lookup, the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension maintains a link to the dictionary key. Therefore, if the value associated with the key is replaced, the change is applied to the <xref:Microsoft.Maui.Controls.VisualElement>. This enables runtime theming to be implemented in .NET MAUI apps.
|
||||
|
||||
The process for implementing runtime theming in a .NET MAUI app is as follows:
|
||||
|
||||
1. Define the resources for each theme in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. For more information, see [Define themes](#define-themes).
|
||||
1. Set a default theme in the app's *App.xaml* file. For more information, see [Set a default theme](#set-a-default-theme).
|
||||
1. Consume theme resources in the app, using the `DynamicResource` markup extension. For more information, see [Consume theme resources](#consume-theme-resources).
|
||||
1. Consume theme resources in the app, using the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension. For more information, see [Consume theme resources](#consume-theme-resources).
|
||||
1. Add code to load a theme at runtime. For more information, see [Load a theme at runtime](#load-a-theme-at-runtime).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Use the `StaticResource` markup extension if you don't need to change the app theme at runtime.
|
||||
> Use the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension if you don't need to change the app theme at runtime.
|
||||
|
||||
The following screenshot shows themed pages, with the iOS app using a light theme and the Android app using a dark theme:
|
||||
|
||||
|
|
@ -67,7 +67,7 @@ The following example shows a <xref:Microsoft.Maui.Controls.ResourceDictionary>
|
|||
</ResourceDictionary>
|
||||
```
|
||||
|
||||
Each <xref:Microsoft.Maui.Controls.ResourceDictionary> contains `Color` resources that define their respective themes, with each <xref:Microsoft.Maui.Controls.ResourceDictionary> using identical key values. For more information about resource dictionaries, see [Resource Dictionaries](~/fundamentals/resource-dictionaries.md).
|
||||
Each <xref:Microsoft.Maui.Controls.ResourceDictionary> contains <xref:Microsoft.Maui.Graphics.Color> resources that define their respective themes, with each <xref:Microsoft.Maui.Controls.ResourceDictionary> using identical key values. For more information about resource dictionaries, see [Resource Dictionaries](~/fundamentals/resource-dictionaries.md).
|
||||
|
||||
> [!IMPORTANT]
|
||||
> A code behind file is required for each <xref:Microsoft.Maui.Controls.ResourceDictionary>, which calls the `InitializeComponent` method. This is necessary so that a CLR object representing the chosen theme can be created at runtime.
|
||||
|
|
@ -90,7 +90,7 @@ For more information about merging resource dictionaries, see [Merged resource d
|
|||
|
||||
## Consume theme resources
|
||||
|
||||
When an app wants to consume a resource that's stored in a <xref:Microsoft.Maui.Controls.ResourceDictionary> that represents a theme, it should do so with the `DynamicResource` markup extension. This ensures that if a different theme is selected at runtime, the values from the new theme will be applied.
|
||||
When an app wants to consume a resource that's stored in a <xref:Microsoft.Maui.Controls.ResourceDictionary> that represents a theme, it should do so with the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension. This ensures that if a different theme is selected at runtime, the values from the new theme will be applied.
|
||||
|
||||
The following example shows three styles from that can be applied to all <xref:Microsoft.Maui.Controls.Label> objects in app:
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ The following example shows three styles from that can be applied to all <xref:M
|
|||
</Application>
|
||||
```
|
||||
|
||||
These styles are defined in the app-level resource dictionary, so that they can be consumed by multiple pages. Each style consumes theme resources with the `DynamicResource` markup extension.
|
||||
These styles are defined in the app-level resource dictionary, so that they can be consumed by multiple pages. Each style consumes theme resources with the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension.
|
||||
|
||||
These styles are then consumed by pages:
|
||||
|
||||
|
|
@ -171,9 +171,9 @@ These styles are then consumed by pages:
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
When a theme resource is consumed directly, it should be consumed with the `DynamicResource` markup extension. However, when a style that uses the `DynamicResource` markup extension is consumed, it should be consumed with the `StaticResource` markup extension.
|
||||
When a theme resource is consumed directly, it should be consumed with the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension. However, when a style that uses the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension is consumed, it should be consumed with the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension.
|
||||
|
||||
For more information about styling, see [Style apps using XAML](~/user-interface/styles/xaml.md). For more information about the `DynamicResource` markup extension, see [Dynamic styles](~/user-interface/styles/xaml.md#dynamic-styles).
|
||||
For more information about styling, see [Style apps using XAML](~/user-interface/styles/xaml.md). For more information about the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension, see [Dynamic styles](~/user-interface/styles/xaml.md#dynamic-styles).
|
||||
|
||||
## Load a theme at runtime
|
||||
|
||||
|
|
@ -182,7 +182,7 @@ When a theme is selected at runtime, an app should:
|
|||
1. Remove the current theme from the app. This is achieved by clearing the `MergedDictionaries` property of the app-level <xref:Microsoft.Maui.Controls.ResourceDictionary>.
|
||||
2. Load the selected theme. This is achieved by adding an instance of the selected theme to the `MergedDictionaries` property of the app-level <xref:Microsoft.Maui.Controls.ResourceDictionary>.
|
||||
|
||||
Any <xref:Microsoft.Maui.Controls.VisualElement> objects that set properties with the `DynamicResource` markup extension will then apply the new theme values. This occurs because the `DynamicResource` markup extension maintains a link to dictionary keys. Therefore, when the values associated with keys are replaced, the changes are applied to the <xref:Microsoft.Maui.Controls.VisualElement> objects.
|
||||
Any <xref:Microsoft.Maui.Controls.VisualElement> objects that set properties with the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension will then apply the new theme values. This occurs because the [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) markup extension maintains a link to dictionary keys. Therefore, when the values associated with keys are replaced, the changes are applied to the <xref:Microsoft.Maui.Controls.VisualElement> objects.
|
||||
|
||||
In the sample application, a theme is selected via a modal page that contains a <xref:Microsoft.Maui.Controls.Picker>. The following code shows the `OnPickerSelectionChanged` method, which is executed when the selected theme changes:
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Data bindings connect properties of two objects, called the *source* and the *ta
|
|||
|
||||
The target property must be a bindable property, which means that the target object must derive from <xref:Microsoft.Maui.Controls.BindableObject>. A property of <xref:Microsoft.Maui.Controls.Label>, such as `Text`, is associated with the bindable property `TextProperty`.
|
||||
|
||||
In XAML, you must also perform the same two steps that are required in code, except that the `Binding` markup extension takes the place of the `SetBinding` call and the `Binding` class. However, when you define data bindings in XAML, there are multiple ways to set the `BindingContext` of the target object. Sometimes it’s set from the code-behind file, sometimes using a `StaticResource` or `x:Static` markup extension, and sometimes as the content of `BindingContext` property-element tags.
|
||||
In XAML, you must also perform the same two steps that are required in code, except that the `Binding` markup extension takes the place of the `SetBinding` call and the `Binding` class. However, when you define data bindings in XAML, there are multiple ways to set the `BindingContext` of the target object. Sometimes it’s set from the code-behind file, sometimes using a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) or `x:Static` markup extension, and sometimes as the content of `BindingContext` property-element tags.
|
||||
|
||||
## View-to-view bindings
|
||||
|
||||
|
|
@ -232,7 +232,7 @@ namespace XamlSamples
|
|||
}
|
||||
```
|
||||
|
||||
Each `NamedColor` object has `Name` and `FriendlyName` properties of type `string`, a `Color` property of type `Color`, and `Red`, `Green`, and `Blue` properties. In addition, the `NamedColor` static constructor creates an `IEnumerable<NamedColor>` collection that contains `NamedColor` objects corresponding to the fields of type `Color` in the <xref:Microsoft.Maui.Graphics.Colors> class, and assigns it to its public static `All` property.
|
||||
Each `NamedColor` object has `Name` and `FriendlyName` properties of type `string`, a `Color` property of type <xref:Microsoft.Maui.Graphics.Color>, and `Red`, `Green`, and `Blue` properties. In addition, the `NamedColor` static constructor creates an `IEnumerable<NamedColor>` collection that contains `NamedColor` objects corresponding to the fields of type <xref:Microsoft.Maui.Graphics.Color> in the <xref:Microsoft.Maui.Graphics.Colors> class, and assigns it to its public static `All` property.
|
||||
|
||||
Setting the static `NamedColor.All` property to the `ItemsSource` of a <xref:Microsoft.Maui.Controls.ListView> can be achieved using the `x:Static` markup extension:
|
||||
|
||||
|
|
@ -250,7 +250,7 @@ The result establishes that the items are of type `XamlSamples.NamedColor`:
|
|||
|
||||
:::image type="content" source="media/data-binding-basics/listview1.png" alt-text="Binding to a collection.":::
|
||||
|
||||
To define a template for the items, the `ItemTemplate` should be set to a `DataTemplate` that references a <xref:Microsoft.Maui.Controls.ViewCell>. The <xref:Microsoft.Maui.Controls.ViewCell> should define a layout of one or more views to display each item:
|
||||
To define a template for the items, the `ItemTemplate` should be set to a <xref:Microsoft.Maui.Controls.DataTemplate> that references a <xref:Microsoft.Maui.Controls.ViewCell>. The <xref:Microsoft.Maui.Controls.ViewCell> should define a layout of one or more views to display each item:
|
||||
|
||||
```xaml
|
||||
<ListView ItemsSource="{x:Static local:NamedColor.All}">
|
||||
|
|
@ -329,7 +329,7 @@ The item template can be expanded to display more information and the actual col
|
|||
|
||||
The previous XAML example displays the individual `Red`, `Green`, and `Blue` properties of each `NamedColor`. These properties are of type `float` and range from 0 to 1. If you want to display the hexadecimal values, you can’t simply use `StringFormat` with an “X2” formatting specification. That only works for integers and besides, the `float` values need to be multiplied by 255.
|
||||
|
||||
This issue can be solved with a *value converter*, also called a *binding converter*. This is a class that implements the `IValueConverter` interface, which means it has two methods named `Convert` and `ConvertBack`. The `Convert` method is called when a value is transferred from source to target. The `ConvertBack` method is called for transfers from target to source in `OneWayToSource` or `TwoWay` bindings:
|
||||
This issue can be solved with a *value converter*, also called a *binding converter*. This is a class that implements the <xref:Microsoft.Maui.Controls.IValueConverter> interface, which means it has two methods named `Convert` and `ConvertBack`. The `Convert` method is called when a value is transferred from source to target. The `ConvertBack` method is called for transfers from target to source in `OneWayToSource` or `TwoWay` bindings:
|
||||
|
||||
```csharp
|
||||
using System.Globalization;
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ In this example, the two resources are values of the structure type `LayoutOptio
|
|||
> [!NOTE]
|
||||
> Optional <xref:Microsoft.Maui.Controls.ResourceDictionary> tags can be included as the child of the `Resources` tags.
|
||||
|
||||
The resources can then be consumed by the <xref:Microsoft.Maui.Controls.Button> objects, by using the `StaticResource` XAML markup extension to set their `HorizontalOptions` and `VerticalOptions` properties:
|
||||
The resources can then be consumed by the <xref:Microsoft.Maui.Controls.Button> objects, by using the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) XAML markup extension to set their `HorizontalOptions` and `VerticalOptions` properties:
|
||||
|
||||
```xaml
|
||||
<Button Text="Do this!"
|
||||
|
|
@ -92,7 +92,7 @@ The resources can then be consumed by the <xref:Microsoft.Maui.Controls.Button>
|
|||
FontSize="24" />
|
||||
```
|
||||
|
||||
The `StaticResource` markup extension is always delimited with curly braces, and includes the dictionary key. The name `StaticResource` distinguishes it from `DynamicResource`, which .NET MAUI also supports. `DynamicResource` is for dictionary keys associated with values that might change at runtime, while `StaticResource` accesses elements from the dictionary just once when the elements on the page are constructed. Whenever the XAML parser encounters a `StaticResource` markup extension, it searches up the visual tree and uses the first <xref:Microsoft.Maui.Controls.ResourceDictionary> it encounters containing that key.
|
||||
The [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension is always delimited with curly braces, and includes the dictionary key. The name [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) distinguishes it from [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension), which .NET MAUI also supports. [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) is for dictionary keys associated with values that might change at runtime, while [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) accesses elements from the dictionary just once when the elements on the page are constructed. Whenever the XAML parser encounters a [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension, it searches up the visual tree and uses the first <xref:Microsoft.Maui.Controls.ResourceDictionary> it encounters containing that key.
|
||||
|
||||
It’s necessary to store doubles in the dictionary for the `BorderWidth`, `Rotation`, and `FontSize` properties. XAML conveniently defines tags for common data types like `x:Double` and `x:Int32`:
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ These additional three resources can be referenced in the same way as the `Layou
|
|||
FontSize="{StaticResource fontSize}" />
|
||||
```
|
||||
|
||||
For resources of type `Color`, you can use the same string representations that you use when directly assigning attributes of these types. Type converters included in .NET MAUI are invoked when the resource is created. It's also possible to use the `OnPlatform` class within the resource dictionary to define different values for the platforms. The following example uses this class for setting different text colors:
|
||||
For resources of type <xref:Microsoft.Maui.Graphics.Color>, you can use the same string representations that you use when directly assigning attributes of these types. Type converters included in .NET MAUI are invoked when the resource is created. It's also possible to use the `OnPlatform` class within the resource dictionary to define different values for the platforms. The following example uses this class for setting different text colors:
|
||||
|
||||
```xaml
|
||||
<OnPlatform x:Key="textColor"
|
||||
|
|
@ -130,7 +130,7 @@ For resources of type `Color`, you can use the same string representations that
|
|||
</OnPlatform>
|
||||
```
|
||||
|
||||
The `OnPlatform` resource gets an `x:Key` attribute because it’s an object in the dictionary, and an `x:TypeArguments` attribute because it’s a generic class. The `iOS`, and `Android` attributes are converted to `Color` values when the object is initialized.
|
||||
The `OnPlatform` resource gets an `x:Key` attribute because it’s an object in the dictionary, and an `x:TypeArguments` attribute because it’s a generic class. The `iOS`, and `Android` attributes are converted to <xref:Microsoft.Maui.Graphics.Color> values when the object is initialized.
|
||||
|
||||
The following example shows the three buttons accessing six shared values:
|
||||
|
||||
|
|
@ -203,10 +203,10 @@ One of the most common types of objects stored in resource dictionaries is the .
|
|||
|
||||
## x:Static Markup Extension
|
||||
|
||||
In addition to the `StaticResource` markup extension, there's also an `x:Static` markup extension. However, while `StaticResource` returns an object from a resource dictionary,`x:Static` accesses a public static field, a public static property, a public constant field, or an enumeration member.
|
||||
In addition to the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension, there's also an `x:Static` markup extension. However, while [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) returns an object from a resource dictionary,`x:Static` accesses a public static field, a public static property, a public constant field, or an enumeration member.
|
||||
|
||||
> [!NOTE]
|
||||
> The `StaticResource` markup extension is supported by XAML implementations that define a resource dictionary, while `x:Static` is an intrinsic part of XAML, as the `x` prefix reveals.
|
||||
> The [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension is supported by XAML implementations that define a resource dictionary, while `x:Static` is an intrinsic part of XAML, as the `x` prefix reveals.
|
||||
|
||||
The following example demonstrates how `x:Static` can explicitly reference static fields and enumeration members:
|
||||
|
||||
|
|
|
|||
|
|
@ -128,7 +128,7 @@ In addition, it’s possible to access individual properties of the `DateTime` p
|
|||
|
||||
MVVM is often used with two-way data bindings for an interactive view based on an underlying data model.
|
||||
|
||||
The following example shows the `HslViewModel` that converts a `Color` value into `Hue`, `Saturation`, and `Luminosity` values, and back again:
|
||||
The following example shows the `HslViewModel` that converts a <xref:Microsoft.Maui.Graphics.Color> value into `Hue`, `Saturation`, and `Luminosity` values, and back again:
|
||||
|
||||
```csharp
|
||||
using System.ComponentModel;
|
||||
|
|
|
|||
|
|
@ -124,7 +124,7 @@ A single object type argument can be specified as a prefixed string argument usi
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, `GenericsDemo.Models` is defined as the `models` XAML namespace, and `System.Collections.Generic` is defined as the `scg` XAML namespace. The `CollectionView.ItemsSource` property is set to a `List<T>` that's instantiated with a `Monkey` type argument. The `List<Monkey>` collection is initialized with multiple `Monkey` items, and a `DataTemplate` that defines the appearance of each `Monkey` object is set as the `ItemTemplate` of the <xref:Microsoft.Maui.Controls.CollectionView>.
|
||||
In this example, `GenericsDemo.Models` is defined as the `models` XAML namespace, and `System.Collections.Generic` is defined as the `scg` XAML namespace. The `CollectionView.ItemsSource` property is set to a `List<T>` that's instantiated with a `Monkey` type argument. The `List<Monkey>` collection is initialized with multiple `Monkey` items, and a <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each `Monkey` object is set as the `ItemTemplate` of the <xref:Microsoft.Maui.Controls.CollectionView>.
|
||||
|
||||
## Multiple type arguments
|
||||
|
||||
|
|
@ -193,4 +193,4 @@ Multiple type arguments can be specified as prefixed string arguments, delimited
|
|||
</ContentPage
|
||||
```
|
||||
|
||||
In this example, `GenericsDemo.Models` is defined as the `models` XAML namespace, and `System.Collections.Generic` is defined as the `scg` XAML namespace. The `CollectionView.ItemsSource` property is set to a `List<T>` that's instantiated with a `KeyValuePair<TKey, TValue>` constraint, with the inner constraint type arguments `string` and `Monkey`. The `List<KeyValuePair<string,Monkey>>` collection is initialized with multiple `KeyValuePair` items, using the non-default `KeyValuePair` constructor, and a `DataTemplate` that defines the appearance of each `Monkey` object is set as the `ItemTemplate` of the <xref:Microsoft.Maui.Controls.CollectionView>. For information on passing arguments to a non-default constructor, see [Pass constructor arguments](pass-arguments.md#pass-constructor-arguments).
|
||||
In this example, `GenericsDemo.Models` is defined as the `models` XAML namespace, and `System.Collections.Generic` is defined as the `scg` XAML namespace. The `CollectionView.ItemsSource` property is set to a `List<T>` that's instantiated with a `KeyValuePair<TKey, TValue>` constraint, with the inner constraint type arguments `string` and `Monkey`. The `List<KeyValuePair<string,Monkey>>` collection is initialized with multiple `KeyValuePair` items, using the non-default `KeyValuePair` constructor, and a <xref:Microsoft.Maui.Controls.DataTemplate> that defines the appearance of each `Monkey` object is set as the `ItemTemplate` of the <xref:Microsoft.Maui.Controls.CollectionView>. For information on passing arguments to a non-default constructor, see [Pass constructor arguments](pass-arguments.md#pass-constructor-arguments).
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ For example, you typically set the `Color` property of <xref:Microsoft.Maui.Cont
|
|||
<BoxView Color="Blue" />
|
||||
```
|
||||
|
||||
However, you might prefer instead to set the `Color` attribute from a value stored in a resource dictionary, or from the value of a static property of a class that you've created, or from a property of type `Color` of another element on the page, or constructed from separate hue, saturation, and luminosity values. All these options are possible using XAML markup extensions.
|
||||
However, you might prefer instead to set the `Color` attribute from a value stored in a resource dictionary, or from the value of a static property of a class that you've created, or from a property of type <xref:Microsoft.Maui.Graphics.Color> of another element on the page, or constructed from separate hue, saturation, and luminosity values. All these options are possible using XAML markup extensions.
|
||||
|
||||
A markup extension is a different way to express an attribute of an element. .NET MAUI XAML markup extensions are usually identifiable by an attribute value that is enclosed in curly braces:
|
||||
|
||||
|
|
@ -31,16 +31,16 @@ Any attribute value in curly braces is *always* a XAML markup extension. However
|
|||
|
||||
In addition to the markup extensions discussed in this article, the following markup extensions are included in .NET MAUI and discussed in other articles:
|
||||
|
||||
- `StaticResource` - reference objects from a resource dictionary. For more information, see [Resource dictionaries**](~/fundamentals/resource-dictionaries.md).
|
||||
- `DynamicResource` - respond to changes in objects in a resource dictionary. For more information, see [Dynamic styles**](~/user-interface/styles/xaml.md#dynamic-styles).
|
||||
- `Binding` - establish a link between properties of two objects. For more information, see [Data binding**](~/fundamentals/data-binding/index.md).
|
||||
- `TemplateBinding` - performs data binding from a control template. For more information, see [Control templates](~/fundamentals/controltemplate.md).
|
||||
- `RelativeSource` - sets the binding source relative to the position of the binding target. For more information, see [Relative bindings](~/fundamentals/data-binding/relative-bindings.md).
|
||||
- [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) - reference objects from a resource dictionary. For more information, see [Resource dictionaries](~/fundamentals/resource-dictionaries.md).
|
||||
- [`DynamicResource`](xref:Microsoft.Maui.Controls.Xaml.DynamicResourceExtension) - respond to changes in objects in a resource dictionary. For more information, see [Dynamic styles](~/user-interface/styles/xaml.md#dynamic-styles).
|
||||
- [`Binding`](xref:Microsoft.Maui.Controls.Xaml.BindingExtension) - establish a link between properties of two objects. For more information, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
- [`TemplateBinding`](xref:Microsoft.Maui.Controls.Xaml.TemplateBindingExtension) - performs data binding from a control template. For more information, see [Control templates](~/fundamentals/controltemplate.md).
|
||||
- [`RelativeSource`](xref:Microsoft.Maui.Controls.Xaml.RelativeSourceExtension) - sets the binding source relative to the position of the binding target. For more information, see [Relative bindings](~/fundamentals/data-binding/relative-bindings.md).
|
||||
<!-- - `ConstraintExpression` - relates the position and size of a child in a `RelativeLayout` to its parent, or a sibling. For more information, see [RelativeLayout](~/user-interface/layouts/relativelayout.md).-->
|
||||
|
||||
## x:Static markup extension
|
||||
|
||||
The `x:Static` markup extension is supported by the `StaticExtension` class. The class has a single property named `Member` of type `string` that you set to the name of a public constant, static property, static field, or enumeration member.
|
||||
The `x:Static` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> class. The class has a single property named `Member` of type `string` that you set to the name of a public constant, static property, static field, or enumeration member.
|
||||
|
||||
One way to use `x:Static` is to first define a class with some constants or static variables, such as this `AppConstants` class:
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ static class AppConstants
|
|||
}
|
||||
```
|
||||
|
||||
The following XAML demonstrates the most verbose approach to instantiating the `StaticExtension` class between `Label.FontSize` property-element tags:
|
||||
The following XAML demonstrates the most verbose approach to instantiating the <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> class between `Label.FontSize` property-element tags:
|
||||
|
||||
```xaml
|
||||
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
|
||||
|
|
@ -71,7 +71,7 @@ The following XAML demonstrates the most verbose approach to instantiating the `
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
The XAML parser also allows the `StaticExtension` class to be abbreviated as `x:Static`:
|
||||
The XAML parser also allows the <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> class to be abbreviated as `x:Static`:
|
||||
|
||||
```xaml
|
||||
<Label Text="Label No. 2">
|
||||
|
|
@ -81,14 +81,14 @@ The XAML parser also allows the `StaticExtension` class to be abbreviated as `x:
|
|||
</Label>
|
||||
```
|
||||
|
||||
This syntax can be simplified even further by putting the `StaticExtension` class and the member setting in curly braces. The resulting expression is set directly to the `FontSize` attribute:
|
||||
This syntax can be simplified even further by putting the <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> class and the member setting in curly braces. The resulting expression is set directly to the `FontSize` attribute:
|
||||
|
||||
```xaml
|
||||
<Label Text="Label No. 3"
|
||||
FontSize="{x:StaticExtension Member=local:AppConstants.NormalFontSize}" />
|
||||
```
|
||||
|
||||
In this example, there are *no* quotation marks within the curly braces. The `Member` property of `StaticExtension` is no longer an XML attribute. It is instead part of the expression for the markup extension.
|
||||
In this example, there are *no* quotation marks within the curly braces. The `Member` property of <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> is no longer an XML attribute. It is instead part of the expression for the markup extension.
|
||||
|
||||
Just as you can abbreviate `x:StaticExtension` to `x:Static` when you use it as an object element, you can also abbreviate it in the expression within curly braces:
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ Just as you can abbreviate `x:StaticExtension` to `x:Static` when you use it as
|
|||
FontSize="{x:Static Member=local:AppConstants.NormalFontSize}" />
|
||||
```
|
||||
|
||||
The `StaticExtension` class has a `ContentProperty` attribute referencing the property `Member`, which marks this property as the class's default content property. For XAML markup extensions expressed with curly braces, you can eliminate the `Member=` part of the expression:
|
||||
The <xref:Microsoft.Maui.Controls.Xaml.StaticExtension> class has a `ContentProperty` attribute referencing the property `Member`, which marks this property as the class's default content property. For XAML markup extensions expressed with curly braces, you can eliminate the `Member=` part of the expression:
|
||||
|
||||
```xaml
|
||||
<Label Text="Label No. 5"
|
||||
|
|
@ -121,7 +121,7 @@ The following screenshot shows the XAML output:
|
|||
|
||||
## x:Reference markup extension
|
||||
|
||||
The `x:Reference` markup extension is supported by the `ReferenceExtension` class. The class has a single property named `Name` of type `string` that you set to the name of an element on the page that has been given a name with `x:Name`. This `Name` property is the content property of `ReferenceExtension`, so `Name=` is not required when `x:Reference` appears in curly braces. The `x:Reference` markup extension is used exclusively with data bindings. For more information about data bindings, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
The `x:Reference` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.ReferenceExtension> class. The class has a single property named `Name` of type `string` that you set to the name of an element on the page that has been given a name with `x:Name`. This `Name` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.ReferenceExtension>, so `Name=` is not required when `x:Reference` appears in curly braces. The `x:Reference` markup extension is used exclusively with data bindings. For more information about data bindings, see [Data binding](~/fundamentals/data-binding/index.md).
|
||||
|
||||
The following XAML example shows two uses of `x:Reference` with data bindings, the first where it's used to set the `Source` property of the `Binding` object, and the second where it's used to set the `BindingContext` property for two data bindings:
|
||||
|
||||
|
|
@ -150,7 +150,7 @@ The following XAML example shows two uses of `x:Reference` with data bindings, t
|
|||
</ContentPage>
|
||||
```
|
||||
|
||||
In this example, both `x:Reference` expressions use the abbreviated version of the `ReferenceExtension` class name and eliminate the `Name=` part of the expression. In the first example, the `x:Reference` markup extension is embedded in the `Binding` markup extension and the `Source` and `StringFormat` properties are separated by commas.
|
||||
In this example, both `x:Reference` expressions use the abbreviated version of the <xref:Microsoft.Maui.Controls.Xaml.ReferenceExtension> class name and eliminate the `Name=` part of the expression. In the first example, the `x:Reference` markup extension is embedded in the `Binding` markup extension and the `Source` and `StringFormat` properties are separated by commas.
|
||||
|
||||
The following screenshot shows the XAML output:
|
||||
|
||||
|
|
@ -158,7 +158,7 @@ The following screenshot shows the XAML output:
|
|||
|
||||
## x:Type markup extension
|
||||
|
||||
The `x:Type` markup extension is the XAML equivalent of the C# [`typeof`](/dotnet/csharp/language-reference/keywords/typeof/) keyword. It's supported by the `TypeExtension` class, which defines a property named `TypeName` of type `string` that should be set to a class or structure name. The `x:Type` markup extension returns the [`Type`](xref:System.Type) object of that class or structure. `TypeName` is the content property of `TypeExtension`, so `TypeName=` is not required when `x:Type` appears with curly braces.
|
||||
The `x:Type` markup extension is the XAML equivalent of the C# [`typeof`](/dotnet/csharp/language-reference/keywords/typeof/) keyword. It's supported by the <xref:Microsoft.Maui.Controls.Xaml.TypeExtension> class, which defines a property named `TypeName` of type `string` that should be set to a class or structure name. The `x:Type` markup extension returns the [`Type`](xref:System.Type) object of that class or structure. `TypeName` is the content property of <xref:Microsoft.Maui.Controls.Xaml.TypeExtension>, so `TypeName=` is not required when `x:Type` appears with curly braces.
|
||||
|
||||
The `x:Type` markup extension is commonly used with the `x:Array` markup extension. For more information, see [x:Array markup extension](#xarray-markup-extension).
|
||||
|
||||
|
|
@ -219,10 +219,10 @@ When a <xref:Microsoft.Maui.Controls.Button> is pressed a new instance of the `C
|
|||
|
||||
## x:Array markup extension
|
||||
|
||||
The `x:Array` markup extension enables you to define an array in markup. It is supported by the `ArrayExtension` class, which defines two properties:
|
||||
The `x:Array` markup extension enables you to define an array in markup. It is supported by the <xref:Microsoft.Maui.Controls.Xaml.ArrayExtension> class, which defines two properties:
|
||||
|
||||
- `Type` of type `Type`, which indicates the type of the elements in the array. This property should be set to an `x:Type` markup extension.
|
||||
- `Items` of type `IList`, which is a collection of the items themselves. This is the content property of `ArrayExtension`.
|
||||
- `Items` of type `IList`, which is a collection of the items themselves. This is the content property of <xref:Microsoft.Maui.Controls.Xaml.ArrayExtension>.
|
||||
|
||||
The `x:Array` markup extension itself never appears in curly braces. Instead, `x:Array` start and end tags delimit the list of items.
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ In this example, the <xref:Microsoft.Maui.Controls.ViewCell> creates a simple <x
|
|||
|
||||
## x:Null markup extension
|
||||
|
||||
The `x:Null` markup extension is supported by the `NullExtension` class. It has no properties and is simply the XAML equivalent of the C# [`null`](/dotnet/csharp/language-reference/keywords/null/) keyword.
|
||||
The `x:Null` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.NullExtension> class. It has no properties and is simply the XAML equivalent of the C# [`null`](/dotnet/csharp/language-reference/keywords/null/) keyword.
|
||||
|
||||
The following XAML example shows how to use the `x:Null` markup extension:
|
||||
|
||||
|
|
@ -311,7 +311,7 @@ In this example, an implicit <xref:Microsoft.Maui.Controls.Style> is defined for
|
|||
|
||||
The `OnPlatform` markup extension enables you to customize UI appearance on a per-platform basis. It provides the same functionality as the `OnPlatform` and `On` classes, but with a more concise representation.
|
||||
|
||||
The `OnPlatform` markup extension is supported by the `OnPlatformExtension` class, which defines the following properties:
|
||||
The `OnPlatform` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension> class, which defines the following properties:
|
||||
|
||||
- `Default` of type `object`, that you set to a default value to be applied to the properties that represent platforms.
|
||||
- `Android` of type `object`, that you set to a value to be applied on Android.
|
||||
|
|
@ -319,16 +319,16 @@ The `OnPlatform` markup extension is supported by the `OnPlatformExtension` clas
|
|||
- `MacCatalyst` of type `object`, that you set to a value to be applied on Mac Catalyst.
|
||||
- `Tizen` of type `object`, that you set to a value to be applied on the Tizen platform.
|
||||
- `WinUI` of type `object`, that you set to a value to be applied on WinUI.
|
||||
- `Converter` of type `IValueConverter`, that can be set to an `IValueConverter` implementation.
|
||||
- `ConverterParameter` of type `object`, that can be set to a value to pass to the `IValueConverter` implementation.
|
||||
- `Converter` of type <xref:Microsoft.Maui.Controls.IValueConverter>, that can be set to an <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
- `ConverterParameter` of type `object`, that can be set to a value to pass to the <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `OnPlatformExtension` class to be abbreviated as `OnPlatform`.
|
||||
> The XAML parser allows the <xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension> class to be abbreviated as `OnPlatform`.
|
||||
|
||||
The `Default` property is the content property of `OnPlatformExtension`. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument. If the `Default` property isn't set, it will default to the `BindableProperty.DefaultValue` property value, provided that the markup extension is targeting a <xref:Microsoft.Maui.Controls.BindableProperty>.
|
||||
The `Default` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension>. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument. If the `Default` property isn't set, it will default to the `BindableProperty.DefaultValue` property value, provided that the markup extension is targeting a <xref:Microsoft.Maui.Controls.BindableProperty>.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The XAML parser expects that values of the correct type will be provided to properties consuming the `OnPlatform` markup extension. If type conversion is necessary, the `OnPlatform` markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the `Converter` property should be set to an `IValueConverter` implementation.
|
||||
> The XAML parser expects that values of the correct type will be provided to properties consuming the `OnPlatform` markup extension. If type conversion is necessary, the `OnPlatform` markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the `Converter` property should be set to an <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
|
||||
The **OnPlatform Demo** page shows how to use the `OnPlatform` markup extension:
|
||||
|
||||
|
|
@ -339,11 +339,11 @@ The **OnPlatform Demo** page shows how to use the `OnPlatform` markup extension:
|
|||
HorizontalOptions="Center" />
|
||||
```
|
||||
|
||||
In this example, all three `OnPlatform` expressions use the abbreviated version of the `OnPlatformExtension` class name. The three `OnPlatform` markup extensions set the `Color`, <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest>, and <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> properties of the <xref:Microsoft.Maui.Controls.BoxView> to different values on iOS and Android. The markup extensions also provide default values for these properties on the platforms that aren't specified, while eliminating the `Default=` part of the expression.
|
||||
In this example, all three `OnPlatform` expressions use the abbreviated version of the <xref:Microsoft.Maui.Controls.Xaml.OnPlatformExtension> class name. The three `OnPlatform` markup extensions set the `xref:Microsoft.Maui.Graphics.Color`, <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest>, and <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> properties of the <xref:Microsoft.Maui.Controls.BoxView> to different values on iOS and Android. The markup extensions also provide default values for these properties on the platforms that aren't specified, while eliminating the `Default=` part of the expression.
|
||||
|
||||
## OnIdiom markup extension
|
||||
|
||||
The `OnIdiom` markup extension enables you to customize UI appearance based on the idiom of the device the application is running on. It's supported by the `OnIdiomExtension` class, which defines the following properties:
|
||||
The `OnIdiom` markup extension enables you to customize UI appearance based on the idiom of the device the application is running on. It's supported by the <xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension> class, which defines the following properties:
|
||||
|
||||
- `Default` of type `object`, that you set to a default value to be applied to the properties that represent device idioms.
|
||||
- `Phone` of type `object`, that you set to a value to be applied on phones.
|
||||
|
|
@ -351,16 +351,16 @@ The `OnIdiom` markup extension enables you to customize UI appearance based on t
|
|||
- `Desktop` of type `object`, that you set to a value to be applied on desktop platforms.
|
||||
- `TV` of type `object`, that you set to a value to be applied on TV platforms.
|
||||
- `Watch` of type `object`, that you set to a value to be applied on Watch platforms.
|
||||
- `Converter` of type `IValueConverter`, that can be set to an `IValueConverter` implementation.
|
||||
- `ConverterParameter` of type `object`, that can be set to a value to pass to the `IValueConverter` implementation.
|
||||
- `Converter` of type <xref:Microsoft.Maui.Controls.IValueConverter>, that can be set to an <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
- `ConverterParameter` of type `object`, that can be set to a value to pass to the <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `OnIdiomExtension` class to be abbreviated as `OnIdiom`.
|
||||
> The XAML parser allows the <xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension> class to be abbreviated as `OnIdiom`.
|
||||
|
||||
The `Default` property is the content property of `OnIdiomExtension`. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument.
|
||||
The `Default` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension>. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The XAML parser expects that values of the correct type will be provided to properties consuming the `OnIdiom` markup extension. If type conversion is necessary, the `OnIdiom` markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the `Converter` property should be set to an `IValueConverter` implementation.
|
||||
> The XAML parser expects that values of the correct type will be provided to properties consuming the `OnIdiom` markup extension. If type conversion is necessary, the `OnIdiom` markup extension will attempt to perform it using the default converters provided by .NET MAUI. However, there are some type conversions that can't be performed by the default converters and in these cases the `Converter` property should be set to an <xref:Microsoft.Maui.Controls.IValueConverter> implementation.
|
||||
|
||||
The following XAML example shows how to use the `OnIdiom` markup extension:
|
||||
|
||||
|
|
@ -371,14 +371,14 @@ The following XAML example shows how to use the `OnIdiom` markup extension:
|
|||
HorizontalOptions="Center" />
|
||||
```
|
||||
|
||||
In this example, all three `OnIdiom` expressions use the abbreviated version of the `OnIdiomExtension` class name. The three `OnIdiom` markup extensions set the `Color`, <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest>, and <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> properties of the <xref:Microsoft.Maui.Controls.BoxView> to different values on the phone, tablet, and desktop idioms. The markup extensions also provide default values for these properties on the idioms that aren't specified, while eliminating the `Default=` part of the expression.
|
||||
In this example, all three `OnIdiom` expressions use the abbreviated version of the <xref:Microsoft.Maui.Controls.Xaml.OnIdiomExtension> class name. The three `OnIdiom` markup extensions set the `Color`, <xref:Microsoft.Maui.Controls.VisualElement.WidthRequest>, and <xref:Microsoft.Maui.Controls.VisualElement.HeightRequest> properties of the <xref:Microsoft.Maui.Controls.BoxView> to different values on the phone, tablet, and desktop idioms. The markup extensions also provide default values for these properties on the idioms that aren't specified, while eliminating the `Default=` part of the expression.
|
||||
|
||||
## DataTemplate markup extension
|
||||
|
||||
The `DataTemplate` markup extension enables you to convert a type into a `DataTemplate`. It's supported by the `DataTemplateExtension` class, which defines a `TypeName` property, of type `string`, that is set to the name of the type to be converted into a `DataTemplate`. The `TypeName` property is the content property of `DataTemplateExtension`. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `TypeName=` part of the expression.
|
||||
The <xref:Microsoft.Maui.Controls.DataTemplate> markup extension enables you to convert a type into a <xref:Microsoft.Maui.Controls.DataTemplate>. It's supported by the <xref:Microsoft.Maui.Controls.Xaml.DataTemplateExtension> class, which defines a `TypeName` property, of type `string`, that is set to the name of the type to be converted into a <xref:Microsoft.Maui.Controls.DataTemplate>. The `TypeName` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.DataTemplateExtension>. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `TypeName=` part of the expression.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `DataTemplateExtension` class to be abbreviated as `DataTemplate`.
|
||||
> The XAML parser allows the <xref:Microsoft.Maui.Controls.Xaml.DataTemplateExtension> class to be abbreviated as <xref:Microsoft.Maui.Controls.DataTemplate>.
|
||||
|
||||
A typical usage of this markup extension is in a Shell application, as shown in the following example:
|
||||
|
||||
|
|
@ -388,7 +388,7 @@ A typical usage of this markup extension is in a Shell application, as shown in
|
|||
ContentTemplate="{DataTemplate views:MonkeysPage}" />
|
||||
```
|
||||
|
||||
In this example, `MonkeysPage` is converted from a <xref:Microsoft.Maui.Controls.ContentPage> to a `DataTemplate`, which is set as the value of the `ShellContent.ContentTemplate` property. This ensures that `MonkeysPage` is only created when navigation to the page occurs, rather than at application startup.
|
||||
In this example, `MonkeysPage` is converted from a <xref:Microsoft.Maui.Controls.ContentPage> to a <xref:Microsoft.Maui.Controls.DataTemplate>, which is set as the value of the `ShellContent.ContentTemplate` property. This ensures that `MonkeysPage` is only created when navigation to the page occurs, rather than at application startup.
|
||||
|
||||
For more information about Shell apps, see [Shell](~/fundamentals/shell/index.md).
|
||||
|
||||
|
|
@ -396,17 +396,17 @@ For more information about Shell apps, see [Shell](~/fundamentals/shell/index.md
|
|||
|
||||
The `FontImage` markup extension enables you to display a font icon in any view that can display an `ImageSource`. It provides the same functionality as the `FontImageSource` class, but with a more concise representation.
|
||||
|
||||
The `FontImage` markup extension is supported by the `FontImageExtension` class, which defines the following properties:
|
||||
The `FontImage` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.FontImageExtension> class, which defines the following properties:
|
||||
|
||||
- `FontFamily` of type `string`, the font family to which the font icon belongs.
|
||||
- `Glyph` of type `string`, the unicode character value of the font icon.
|
||||
- `Color` of type `Color`, the color to be used when displaying the font icon.
|
||||
- `Color` of type <xref:Microsoft.Maui.Graphics.Color>, the color to be used when displaying the font icon.
|
||||
- `Size` of type `double`, the size, in device-independent units, of the rendered font icon. The default value is 30. In addition, this property can be set to a named font size.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `FontImageExtension` class to be abbreviated as `FontImage`.
|
||||
> The XAML parser allows the <xref:Microsoft.Maui.Controls.Xaml.FontImageExtension> class to be abbreviated as `FontImage`.
|
||||
|
||||
The `Glyph` property is the content property of `FontImageExtension`. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Glyph=` part of the expression provided that it's the first argument.
|
||||
The `Glyph` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.FontImageExtension>. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Glyph=` part of the expression provided that it's the first argument.
|
||||
|
||||
The following XAML example shows how to use the `FontImage` markup extension:
|
||||
|
||||
|
|
@ -415,7 +415,7 @@ The following XAML example shows how to use the `FontImage` markup extension:
|
|||
Source="{FontImage , FontFamily=Ionicons, Size=44}" />
|
||||
```
|
||||
|
||||
In this example, the abbreviated version of the `FontImageExtension` class name is used to display an XBox icon, from the Ionicons font family, in an <xref:Microsoft.Maui.Controls.Image>:
|
||||
In this example, the abbreviated version of the <xref:Microsoft.Maui.Controls.Xaml.FontImageExtension> class name is used to display an XBox icon, from the Ionicons font family, in an <xref:Microsoft.Maui.Controls.Image>:
|
||||
|
||||
:::image type="content" source="media/consume/fontimagedemo.png" alt-text="Screenshot of the FontImage markup extension.":::
|
||||
|
||||
|
|
@ -430,7 +430,7 @@ The `AppThemeBinding` markup extension enables you to specify a resource to be c
|
|||
<!-- > [!IMPORTANT]
|
||||
> The `AppThemeBinding` markup extension has minimum operating system requirements. For more information, see [Respond to system theme changes in .NET MAUI applications](~/xamarin-forms/user-interface/theming/system-theme-changes.md). -->
|
||||
|
||||
The `AppThemeBinding` markup extension is supported by the `AppThemeBindingExtension` class, which defines the following properties:
|
||||
The `AppThemeBinding` markup extension is supported by the <xref:Microsoft.Maui.Controls.Xaml.AppThemeBindingExtension> class, which defines the following properties:
|
||||
|
||||
- `Default`, of type `object`, that you set to the resource to be used by default.
|
||||
- `Light`, of type `object`, that you set to the resource to be used when the device is using its light theme.
|
||||
|
|
@ -438,9 +438,9 @@ The `AppThemeBinding` markup extension is supported by the `AppThemeBindingExten
|
|||
- `Value`, of type `object`, that returns the resource that's currently being used by the markup extension.
|
||||
|
||||
> [!NOTE]
|
||||
> The XAML parser allows the `AppThemeBindingExtension` class to be abbreviated as `AppBindingTheme`.
|
||||
> The XAML parser allows the <xref:Microsoft.Maui.Controls.Xaml.AppThemeBindingExtension> class to be abbreviated as `AppBindingTheme`.
|
||||
|
||||
The `Default` property is the content property of `AppThemeBindingExtension`. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument.
|
||||
The `Default` property is the content property of <xref:Microsoft.Maui.Controls.Xaml.AppThemeBindingExtension>. Therefore, for XAML markup expressions expressed with curly braces, you can eliminate the `Default=` part of the expression provided that it's the first argument.
|
||||
|
||||
The following XAML example shows how to use the `AppThemeBinding` markup extension:
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Often, XAML markup extensions define properties that contribute to the return va
|
|||
|
||||
## Create a markup extension
|
||||
|
||||
The following XAML markup extension demonstrates how to create your own markup extension. It allows you to construct a `Color` value using hue, saturation, and luminosity components. It defines four properties for the four components of the color, including an alpha component that is initialized to 1. The class derives from `IMarkupExtension<Color>` to indicate a `Color` return value:
|
||||
The following XAML markup extension demonstrates how to create your own markup extension. It allows you to construct a <xref:Microsoft.Maui.Graphics.Color> value using hue, saturation, and luminosity components. It defines four properties for the four components of the color, including an alpha component that is initialized to 1. The class derives from `IMarkupExtension<Color>` to indicate a <xref:Microsoft.Maui.Graphics.Color> return value:
|
||||
|
||||
```csharp
|
||||
public class HslColorExtension : IMarkupExtension<Color>
|
||||
|
|
@ -57,7 +57,7 @@ public class HslColorExtension : IMarkupExtension<Color>
|
|||
}
|
||||
```
|
||||
|
||||
Because `IMarkupExtension<T>` derives from `IMarkupExtension`, the class must contain two `ProvideValue` methods, one that returns a `Color` and another that returns an `object`, but the second method can call the first method.
|
||||
Because `IMarkupExtension<T>` derives from `IMarkupExtension`, the class must contain two `ProvideValue` methods, one that returns a <xref:Microsoft.Maui.Graphics.Color> and another that returns an `object`, but the second method can call the first method.
|
||||
|
||||
## Consume a markup extension
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ The following table outlines the `x` constructs supported by .NET MAUI:
|
|||
|`x:DataType`|Specifies the type of the object that the XAML element, and it's children, will bind to.|
|
||||
|`x:FactoryMethod`|Specifies a factory method that can be used to initialize an object.|
|
||||
|`x:FieldModifier`|Specifies the access level for generated fields for named XAML elements.|
|
||||
|`x:Key`|Specifies a unique user-defined key for each resource in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The key's value is used to retrieve the XAML resource, and is typically used as the argument for the `StaticResource` markup extension.|
|
||||
|`x:Key`|Specifies a unique user-defined key for each resource in a <xref:Microsoft.Maui.Controls.ResourceDictionary>. The key's value is used to retrieve the XAML resource, and is typically used as the argument for the [`StaticResource`](xref:Microsoft.Maui.Controls.Xaml.StaticResourceExtension) markup extension.|
|
||||
|`x:Name`|Specifies a runtime object name for the XAML element. Setting `x:Name` is similar to declaring a variable in code.|
|
||||
|`x:TypeArguments`|Specifies the generic type arguments to the constructor of a generic type.|
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ With the exception of `x:DateTime`, the other language primitives are in the XAM
|
|||
|
||||
Arguments can be passed to a non-default constructor using the `x:Arguments` attribute. Each constructor argument must be delimited within an XML element that represents the type of the argument.
|
||||
|
||||
The following example demonstrates using the `x:Arguments` attribute with three different `Color` constructors:
|
||||
The following example demonstrates using the `x:Arguments` attribute with three different <xref:Microsoft.Maui.Graphics.Color> constructors:
|
||||
|
||||
```xaml
|
||||
<BoxView HeightRequest="150"
|
||||
|
|
@ -82,13 +82,13 @@ The following example demonstrates using the `x:Arguments` attribute with three
|
|||
</BoxView>
|
||||
```
|
||||
|
||||
The number of elements within the `x:Arguments` tag, and the types of these elements, must match one of the `Color` constructors. The `Color` constructor with a single parameter requires a grayscale `float` value from 0 (black) to 1 (white). The `Color` constructor with three parameters requires `float` red, green, and blue values ranging from 0 to 1. The `Color` constructor with four parameters adds a `float` alpha channel as the fourth parameter.
|
||||
The number of elements within the `x:Arguments` tag, and the types of these elements, must match one of the <xref:Microsoft.Maui.Graphics.Color> constructors. The <xref:Microsoft.Maui.Graphics.Color> constructor with a single parameter requires a grayscale `float` value from 0 (black) to 1 (white). The <xref:Microsoft.Maui.Graphics.Color> constructor with three parameters requires `float` red, green, and blue values ranging from 0 to 1. The <xref:Microsoft.Maui.Graphics.Color> constructor with four parameters adds a `float` alpha channel as the fourth parameter.
|
||||
|
||||
## Call factory methods
|
||||
|
||||
Factory methods can be called in .NET MAUI XAML by specifying the method's name using the `x:FactoryMethod` attribute, and its arguments using the `x:Arguments` attribute. A factory method is a `public static` method that returns objects or values of the same type as the class or structure that defines the methods.
|
||||
|
||||
The `Color` structure defines a number of factory methods, and the following example demonstrates calling three of them:
|
||||
The <xref:Microsoft.Maui.Graphics.Color> class defines a number of factory methods, and the following example demonstrates calling three of them:
|
||||
|
||||
```xaml
|
||||
<BoxView HeightRequest="150"
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче