diff --git a/docs/maui/markup/extensions/bindable-object-extensions.md b/docs/maui/markup/extensions/bindable-object-extensions.md index df616a8f..9d3ed77a 100644 --- a/docs/maui/markup/extensions/bindable-object-extensions.md +++ b/docs/maui/markup/extensions/bindable-object-extensions.md @@ -2,7 +2,7 @@ title: BindableObject extensions - .NET MAUI Community Toolkit author: bijington description: The BindableObject extensions provide a series of extension methods that support configuring Bindings on a BindableObject. -ms.date: 03/27/2022 +ms.date: 07/21/2026 --- # BindableObject extensions @@ -42,23 +42,18 @@ new Entry() ### Complex (Nested) Bindings -When binding to a property inside of a property (also known as "Nested Bindings"), the `handlers` parameter is required. The `handler` parameter requires a reference to each Property in the complex binding chain. +When binding to a property inside of a property (also known as "Nested Bindings"), the `getter` expression can point directly to the nested property; the complete property path is resolved automatically from the expression. Along with the example below, you can find additonal examples of complex bindings in the [Unit Tests for `CommunityToolkit.Maui.Markup`](https://github.com/CommunityToolkit/Maui.Markup/blob/08459a7e128de0e764f4e293cc191bfa293b79bd/src/CommunityToolkit.Maui.Markup.UnitTests/TypedBindingExtensionsTests.cs#L308-L461). #### Complex (Nested) Bindings Example -Using the below `ViewModel` class, we can create a nested two-way binding directly to `ViewModel.NestedObject.Text` using the `handlers` parameter: +Using the below `ViewModel` class, we can create a nested two-way binding directly to `ViewModel.NestedObject.Text`: ```csharp new Entry().Bind( Entry.TextProperty, getter: static (ViewModel vm) => vm.NestedObject.Text, - handlers: - [ - (vm => vm, nameof(ViewModel.NestedObject)), - (vm => vm.NestedObject, nameof(ViewModel.NestedObject.Text)), - ], setter: static (ViewModel vm, string text) => vm.NestedObject.Text = text); ``` @@ -76,6 +71,20 @@ class NestedObject } ``` +When using the `Bind` overloads that accept a `Func`-based `getter`, the `handlers` parameter is required instead. The `handlers` parameter requires a reference to each Property in the complex binding chain: + +```csharp +new Entry().Bind( + Entry.TextProperty, + getter: static (ViewModel vm) => vm.NestedObject.Text, + handlers: + [ + (vm => vm, nameof(ViewModel.NestedObject)), + (vm => vm.NestedObject, nameof(ViewModel.NestedObject.Text)), + ], + setter: static (ViewModel vm, string text) => vm.NestedObject.Text = text); +``` + #### Default property The `Bind` method can be called without specifying the property to set the binding up for, this will utilize the defaults provided by the library with the full list at the [GitHub repository](https://github.com/CommunityToolkit/Maui.Markup/blob/523ff96160889f0806f7686e25c5d651fa7d8b7e/src/CommunityToolkit.Maui.Markup/DefaultBindableProperties.cs). @@ -131,6 +140,19 @@ new Label() convert: ((bool IsBusy, string LabelText) values) => values.IsBusy ? string.Empty : values.LabelText) ``` +## RemoveTypedBinding + +The `RemoveTypedBinding` method removes a typed binding from a `BindableObject`. For typed bindings created with a `setter` (for example `TwoWay` or `OneWayToSource` bindings), use this method instead of `RemoveBinding` so that the handlers responsible for writing values back to the binding source are also detached. + +```csharp +var entry = new Entry() + .Bind(Entry.TextProperty, + getter: static (RegistrationViewModel vm) => vm.RegistrationCode, + setter: static (RegistrationViewModel vm, string code) => vm.RegistrationCode = code); + +entry.RemoveTypedBinding(Entry.TextProperty); +``` + ## BindCommand The `BindCommand` method provides a helpful way of configuring a binding to a default provided by the library with the full list at the [GitHub repository](https://github.com/CommunityToolkit/Maui.Markup/blob/523ff96160889f0806f7686e25c5d651fa7d8b7e/src/CommunityToolkit.Maui.Markup/DefaultBindableProperties.cs). @@ -153,6 +175,17 @@ new Button() mode: BindingMode.OneTime); ``` +A `CommandParameter` binding can also be configured by supplying the `parameterGetter` argument: + +```csharp +new Button().BindCommand( + static (ViewModel vm) => vm.SubmitCommand, + parameterGetter: static (ViewModel vm) => vm.RegistrationCode); +``` + +> [!NOTE] +> When a `parameterGetter` is supplied without also supplying `parameterHandlers`, a `parameterSetter` or an explicit `parameterBindingMode`, the `CommandParameter` binding defaults to `BindingMode.OneTime`. + ## Gesture Binding Gesture bindings allow us to create an `ClickGestureRecognizer`, `SwipeGestureRecognizer`, `TapGestureRecognizer`, attach it to any element that implements `IGestureRecognizer` and bind it to an `ICommand` in our ViewModel. diff --git a/docs/maui/markup/extensions/dynamic-resource-handler-extensions.md b/docs/maui/markup/extensions/dynamic-resource-handler-extensions.md index f6d4bda1..e9a33185 100644 --- a/docs/maui/markup/extensions/dynamic-resource-handler-extensions.md +++ b/docs/maui/markup/extensions/dynamic-resource-handler-extensions.md @@ -1,19 +1,19 @@ --- title: DynamicResourceHandler extensions - .NET MAUI Community Toolkit author: TheCodeTraveler -description: The Dynamic Resource Handler extensions provide a series of extension methods that support configuring IDynamicResourceHandler -ms.date: 05/16/2022 +description: The Dynamic Resource Handler extensions provide a series of extension methods that support configuring dynamic resources on an Element +ms.date: 07/21/2026 --- # DynamicResourceHandler extensions -The `DynamicResourceHandler` extensions provide a series of extension methods that support configuring `IDynamicResourceHandler` which can be used to [Theme an App](/dotnet/maui/user-interface/theming). +The `DynamicResourceHandler` extensions provide a series of extension methods that support configuring dynamic resources on any `Element` which can be used to [Theme an App](/dotnet/maui/user-interface/theming). The extensions offer the following methods: ## DynamicResource -The `DynamicResource` method sets the `DynamicResource` property on a control implementing `IDynamicResourceHandler`. +The `DynamicResource` method sets a `DynamicResource` on any control inheriting from `Element`. The following example binds `Label.TextColorProperty` to the [ResourceDictionary][resource-dictionaries-url] key `TextColor`: @@ -23,13 +23,13 @@ new Label().DynamicResource(Label.TextColorProperty, "TextColor"); ## DynamicResources -The `DynamicResources` method sets multiple `DynamicResource` properties on a control implementing `IDynamicResourceHandler`. +The `DynamicResources` method sets multiple `DynamicResource` properties on any control inheriting from `Element`. The following example binds `Label.TextColorProperty` to the [ResourceDictionary][resource-dictionaries-url] key `TextColor`, and also binds `Label.FontFamilyProperty` to the [ResourceDictionary][resource-dictionaries-url] key `FontFamily`, ```csharp -new Label().DynamicResources(Label.TextColorProperty, "TextColor", - Label.FontFamilyProperty, "FontFamily"); +new Label().DynamicResources((Label.TextColorProperty, "TextColor"), + (Label.FontFamilyProperty, "FontFamily")); ``` [resource-dictionaries-url]: /dotnet/maui/fundamentals/resource-dictionaries "Microsoft .NET MAUI Resource Dictionaries documentation" \ No newline at end of file diff --git a/docs/maui/markup/extensions/element-extensions.md b/docs/maui/markup/extensions/element-extensions.md index 547eadc0..7dd41f48 100644 --- a/docs/maui/markup/extensions/element-extensions.md +++ b/docs/maui/markup/extensions/element-extensions.md @@ -2,7 +2,7 @@ title: Element extensions - .NET MAUI Community Toolkit author: TheCodeTraveler description: The Element extensions provide a series of extension methods that support configuring the sizing, styling and behaviors of an Element. -ms.date: 03/28/2022 +ms.date: 07/21/2026 --- # Element extensions @@ -11,7 +11,7 @@ The `Element` extensions provide a series of extension methods that support conf ## Padding -The `Padding` method sets the `Padding` property on an `IPaddingElement`. +The `Padding` method sets the `Padding` property on any element that supports padding: `Border`, `Button`, `ContentPresenter`, `ImageButton`, `Label`, `Layout`, `Page`, `ScrollView`, and `TemplatedView`. The following example sets the `Padding` to `new Thickness(5, 10)`: @@ -31,7 +31,7 @@ new Button().Paddings(10, 20, 30, 40); ## RemoveDynamicResources -The `RemoveDynamicResources` method removes all dynamic resources from a specified `BindableObject`. +The `RemoveDynamicResources` method removes all dynamic resources from a specified `Element`. The following example removes the `DynamicResource` from the `BackgroundColorProperty` and `TextColorProperty`: @@ -55,7 +55,7 @@ new Button().Effects(new ShadowEffect(), new TouchEffect()); ## Font Size -The `FontSize` method sets the `FontSize` property on an `IFontElement` element. +The `FontSize` method sets the `FontSize` property on an `ITextStyle` element. The following example sets the `FontSize` to `12`: @@ -65,7 +65,7 @@ new Button().FontSize(12); ## Bold -The `Bold` method sets `FontAttributes = FontAttributes.Bold` on an `IFontElement` element. +The `Bold` method sets `FontAttributes = FontAttributes.Bold` on an `ITextStyle` element. The following example sets the button font to bold: @@ -75,7 +75,7 @@ new Button().Bold() ## Italic -The `Italic` method sets `FontAttributes = FontAttributes.Italic` on an `IFontElement` element. +The `Italic` method sets `FontAttributes = FontAttributes.Italic` on an `ITextStyle` element. The following example sets the button font to italic: @@ -85,7 +85,7 @@ new Button().Italic() ## Font -The `Font` method sets `FontFamily`, `FontSize`, and `FontAttributes` on an `IFontElement` element. +The `Font` method sets `FontFamily`, `FontSize`, and `FontAttributes` on an `ITextStyle` element. The following example sets the button font to italic: diff --git a/docs/maui/markup/extensions/image-extensions.md b/docs/maui/markup/extensions/image-extensions.md index 762d06dc..224da809 100644 --- a/docs/maui/markup/extensions/image-extensions.md +++ b/docs/maui/markup/extensions/image-extensions.md @@ -1,19 +1,19 @@ --- title: Image extensions - .NET MAUI Community Toolkit author: TheCodeTraveler -description: The Image extensions provide a series of extension methods that support configuring IImage controls -ms.date: 03/28/2022 +description: The Image extensions provide a series of extension methods that support configuring Image and ImageButton controls +ms.date: 07/21/2026 --- # Image extensions -The `Image` extensions provide a series of extension methods that support configuring `IImage` controls. +The `Image` extensions provide a series of extension methods that support configuring `Image` and `ImageButton` controls. The extensions offer the following methods: ## Source -The `Source` method sets the `Source` property on an `IImage` element. +The `Source` method sets the `Source` property on an `Image` or `ImageButton` element. The following example sets the `Source` to `"dotnet_bot"`: @@ -23,7 +23,7 @@ new Image().Source("dotnet_bot"); ## Aspect -The `Aspect` method sets the `Aspect` property on an `IImage` element. +The `Aspect` method sets the `Aspect` property on an `Image` or `ImageButton` element. The following example sets the `Aspect` to `Aspect.AspectFill`: @@ -33,7 +33,7 @@ new Image().Aspect(Aspect.AspectFill); ## IsOpaque -The `IsOpaque` method sets the `IsOpaque` property on an `IImage` element. +The `IsOpaque` method sets the `IsOpaque` property on an `Image` or `ImageButton` element. The following example sets the `IsOpaque` to `true`: diff --git a/docs/maui/markup/extensions/placeholder-extensions.md b/docs/maui/markup/extensions/placeholder-extensions.md index acda0d60..71baffa6 100644 --- a/docs/maui/markup/extensions/placeholder-extensions.md +++ b/docs/maui/markup/extensions/placeholder-extensions.md @@ -1,19 +1,19 @@ --- title: Placeholder extensions - .NET MAUI Community Toolkit author: TheCodeTraveler -description: The Placeholder extensions provide a series of extension methods that support configuring IPlaceholder controls -ms.date: 03/28/2022 +description: The Placeholder extensions provide a series of extension methods that support configuring InputView and SearchHandler controls +ms.date: 07/21/2026 --- # Placeholder extensions -The `Placeholder` extensions provide a series of extension methods that support configuring `IPlaceholder` controls. +The `Placeholder` extensions provide a series of extension methods that support configuring controls that offer a placeholder: `InputView` controls (such as `Editor`, `Entry`, and `SearchBar`) and `SearchHandler`. The extensions offer the following methods: ## PlaceholderColor -The `PlaceholderColor` method sets the `PlaceholderColor` property on an `IPlaceholder` element. +The `PlaceholderColor` method sets the `PlaceholderColor` property on an `InputView` or `SearchHandler` element. The following example sets the `PlaceholderColor` to `Colors.Red`: @@ -23,7 +23,7 @@ new Entry().PlaceholderColor(Colors.Red); ## Placeholder -The `Placeholder` method sets the `Placeholder` property on an `IPlaceholder` element. +The `Placeholder` method sets the `Placeholder` property on an `InputView` or `SearchHandler` element. The following example sets the `Placeholder` to `"Enter Text"`: @@ -31,7 +31,7 @@ The following example sets the `Placeholder` to `"Enter Text"`: new Entry().Placeholder("Enter Text"); ``` -There is a second, overloaded, method for `Placeholder` that will set both the `Placeholder` and `PlaceholderColor` properties on an `IPlaceholder` element. +There is a second, overloaded, method for `Placeholder` that will set both the `Placeholder` and `PlaceholderColor` properties on an `InputView` or `SearchHandler` element. The following example sets the `Placeholder` to `"Address, City, State"` and the `PlaceholderColor` to `Colors.Grey`: diff --git a/docs/maui/markup/markup.md b/docs/maui/markup/markup.md index c0cfb438..28b3d20c 100644 --- a/docs/maui/markup/markup.md +++ b/docs/maui/markup/markup.md @@ -115,14 +115,14 @@ The C# Markup package provides the ability to define [`IValueConverter`](xref:Mi | [`AutomationProperties`](extensions/automation-properties.md) | The `AutomationProperties` extensions provide a series of extension methods that support the configuring of accessibility related settings. | | [`BindableLayout`](extensions/bindable-layout-extensions.md) | The `BindableLayout` extensions provide a series of extension methods that support configuring its `EmptyView`, `ItemSource` and `ItemTemplate`. | | [`BindableObject`](extensions/bindable-object-extensions.md) | The [`BindableObject`](xref:Microsoft.Maui.Controls.BindableObject) extensions provide a series of extension methods that support configuring [`Binding`](xref:Microsoft.Maui.Controls.Binding)s on a [`BindableObject`](xref:Microsoft.Maui.Controls.BindableObject). | -| [`DynamicResourceHandler`](extensions/dynamic-resource-handler-extensions.md) | The `DynamicResourceHandler` extensions provide a series of extension methods that support configuring `IDynamicResourceHandler` which can be used to theme an App. | +| [`DynamicResourceHandler`](extensions/dynamic-resource-handler-extensions.md) | The `DynamicResourceHandler` extensions provide a series of extension methods that support configuring dynamic resources on an [`Element`](xref:Microsoft.Maui.Controls.Element) which can be used to theme an App. | | [`Element`](extensions/element-extensions.md) | The [`Element`](xref:Microsoft.Maui.Controls.Element) extensions provide a series of extension methods that support configuring the padding, effects, font attributes, dynamic resources, text, and text color of an [`Element`](xref:Microsoft.Maui.Controls.Element). | | [`FlexLayout`](extensions/flex-layout-extensions.md) | The FlexLayout extensions provide a series of extension methods that support positioning a [`View`](xref:Microsoft.Maui.Controls.View) in a [`FlexLayout`](xref:Microsoft.Maui.Controls.FlexLayout). | | [`Grid`](extensions/grid-extensions.md) | The Grid extensions provide a series of extension methods that support configuring a Grid. | -| [`Image`](extensions/image-extensions.md) | The [`Image`](xref:Microsoft.Maui.Controls.Image) extensions provide a series of extension methods that support configuring [`IImage`](xref:Microsoft.Maui.IImage) controls. | +| [`Image`](extensions/image-extensions.md) | The [`Image`](xref:Microsoft.Maui.Controls.Image) extensions provide a series of extension methods that support configuring [`Image`](xref:Microsoft.Maui.Controls.Image) and [`ImageButton`](xref:Microsoft.Maui.Controls.ImageButton) controls. | | [`ItemsView`](extensions/itemsview-extensions.md) | The [`ItemsView`](xref:Microsoft.Maui.Controls.ItemsView) extensions provide a series of extension methods that support configuring [`ItemsView`](xref:Microsoft.Maui.Controls.ItemsView) controls such as [`CarouselView`](xref:Microsoft.Maui.Controls.CarouselView) and [`CollectionView`](xref:Microsoft.Maui.Controls.CollectionView). | | [`Label`](extensions/label-extensions.md) | The [`Label`](xref:Microsoft.Maui.Controls.Label) extensions provide a series of extension methods that support configuring [`Label`](xref:Microsoft.Maui.Controls.Label) controls. | -| [`Placeholder`](extensions/placeholder-extensions.md) | The `Placeholder` extensions provide a series of extension methods that support configuring [`IPlaceholder`](xref:Microsoft.Maui.IPlaceholder) controls. | +| [`Placeholder`](extensions/placeholder-extensions.md) | The `Placeholder` extensions provide a series of extension methods that support configuring [`InputView`](xref:Microsoft.Maui.Controls.InputView) and [`SearchHandler`](xref:Microsoft.Maui.Controls.SearchHandler) controls. | | [`SemanticProperties`](extensions/semantic-properties.md) | The `SemanticProperties` extensions provide a series of extension methods that support the configuring of accessibility related settings. | | [`Style`](extensions/style.md) | `Style` provides a series of fluent extension methods that support configuring [`Microsoft.Maui.Controls.Style`](xref:Microsoft.Maui.Controls.Style). | | [`TextAlignment`](extensions/text-alignment-extensions.md) | The `TextAlignment` extensions provide a series of extension methods that support configuring the `HorizontalTextAlignment` and `VeticalTextAlignment` properties on controls implementing [`ITextAlignment`](xref:Microsoft.Maui.ITextAlignment). |