diff --git a/docs/maui/essentials/speech-to-text.md b/docs/maui/essentials/speech-to-text.md index 6a7d61524..b0b629ccf 100644 --- a/docs/maui/essentials/speech-to-text.md +++ b/docs/maui/essentials/speech-to-text.md @@ -145,6 +145,7 @@ The `SpeechToTextOptions` class provides the ability to configure the speech rec |---------|---------|---------| | Culture | `CultureInfo` | The spoken language to use for speech recognition. | | ShouldReportPartialResults | `bool` | Gets or sets if include partial results. `True` by default. | +| AutoStopSilenceTimeout | `TimeSpan` | The duration of continuous silence after which speech recognition will automatically stop. `TimeSpan.MaxValue` by default indicates that auto-stop based on silence is disabled. | ### SpeechToTextResult diff --git a/docs/maui/markup/extensions/bindable-object-extensions.md b/docs/maui/markup/extensions/bindable-object-extensions.md index c3180a550..94f0135cf 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 @@ -40,7 +40,32 @@ new Entry() setter: static (RegistrationViewModel vm, string code) => vm.RegistrationCode = code) ``` -#### BindingBase binding +#### Complex (Nested) Bindings Example + +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, + setter: static (ViewModel vm, string text) => vm.NestedObject.Text = text); +``` + +```cs +class ViewModel +{ + public NestedObject NestedObject { get; set; } = new(); + + public string Text { get; set; } = string.Empty; +} + +class NestedObject +{ + public string Text { get; set; } = string.Empty; +} +``` + +#### Compiled Bindings BindingBase bindings support compiled bindings created with the [BindingBase.Create](/dotnet/api/microsoft.maui.controls.bindingbase.create) method. This approach supports nested, one-way, and two-way bindings. For example, the following code creates a nested two-way binding to `ViewModel.NestedObject.Text`: @@ -105,6 +130,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). @@ -127,6 +165,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 f6d4bda12..e9a33185f 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 547eadc0e..7dd41f482 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 762d06dc2..224da809d 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 acda0d60a..71baffa6f 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 c0cfb4383..28b3d20ca 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). | diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 3da671187..f603317e2 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -13,6 +13,7 @@ ms.date: 02/15/2024 - The web, using a URI (HTTP or HTTPS). - A resource embedded in the platform application, using the `embed://` URI scheme. - Files that come from the app's local filesystem, using the `filesystem://` URI scheme. +- Any valid source via a `Stream`. `MediaElement` can use the platform playback controls, which are referred to as transport controls. However, they are disabled by default and can be replaced with your own transport controls. The following screenshots show `MediaElement` playing a video with the platform transport controls: @@ -222,7 +223,7 @@ Local media can be played from the following sources: - Files that come from the app's local filesystem, using the `filesystem://` URI scheme. > [!NOTE] -> The shorthand `embed://` and `filesystem://` only work from XAML. In code, please use `MediaSource.FromResource()` and `MediaSource.FromFile()` respectively. Using these methods, you can omit the the `embed://` and `filesystem://` prefixes. The rest of the path should be the same. +> The shorthand `embed://` and `filesystem://` only work when `Source` is set from a string in XAML. In code, please use `MediaSource.FromResource()` and `MediaSource.FromFile()` respectively. Using these methods, you can omit the `embed://` and `filesystem://` prefixes. The rest of the path should be the same. Stream-backed sources don't have an equivalent URI-style XAML shorthand. To use a stream source with XAML, bind `Source` to a `MediaSource` instance created in code. ### Play media embedded in the app package @@ -239,13 +240,52 @@ An example of how to use this syntax in XAML can be seen below. ShouldShowPlaybackControls="True" /> ``` +### Play media from a Stream + +You can play media from a `Stream`, which enables scenarios where end-to-end capture and playback remains in memory. + +Consider for example capturing a video using [`MediaPicker`](/dotnet/maui/platform-integration/device-media/picker): + +```csharp +var videoResult = await MediaPicker.Default.CaptureVideoAsync(new MediaPickerOptions +{ + Title = "Capture Video" +}); + +if (videoResult is null) +{ + return; +} +``` + +`videoResult` is a `FileResult`, and its stream can be read by a `MediaElement`. + + +```xaml + +``` + +Copying it to a new stream lets you reset the position to 0 so the `MediaElement` can read it correctly. Keep that stream alive for the duration of playback, and dispose it when it's no longer needed. + +```csharp +await using var stream = await videoResult.OpenReadAsync(); +var memoryStream = new MemoryStream(); +await stream.CopyToAsync(memoryStream); +memoryStream.Position = 0; + +MyMediaElement.Source = MediaSource.FromStream(memoryStream); +``` + +This may be particularly useful for scenarios with security requirements that don't allow saving data outside the app's sandboxed environment. + ## Understand MediaSource types -A `MediaElement` can play media by setting its `Source` property to a remote or local media file. The `Source` property is of type `MediaSource`, and this class defines three static methods: +A `MediaElement` can play media by setting its `Source` property to a remote or local media file. The `Source` property is of type `MediaSource`, and this class defines four static methods: - `FromFile`, returns a `FileMediaSource` instance from a `string` argument. - `FromUri`, returns a `UriMediaSource` instance from a `Uri` argument. - `FromResource`, returns a `ResourceMediaSource` instance from a `string` argument. +- `FromStream`, returns a `StreamMediaSource` instance from a `Stream` argument. In addition, the `MediaSource` class also has implicit operators that return `MediaSource` instances from `string` and `Uri` arguments. @@ -257,6 +297,7 @@ The `MediaSource` class also has these derived classes: - `FileMediaSource`, which is used to specify a local media file from a `string`. This class has a `Path` property that can be set to a `string`. In addition, this class has implicit operators to convert a `string` to a `FileMediaSource` object, and a `FileMediaSource` object to a `string`. - `UriMediaSource`, which is used to specify a remote media file from a URI. This class has a `Uri` property that can be set to a `Uri`. - `ResourceMediaSource`, which is used to specify an embedded file that is provided through the app's resource files. This class has a `Path` property that can be set to a `string`. +- `StreamMediaSource`, which is used to specify a stream that is read incrementally from memory, a file, or a remote source. > [!NOTE] > When a `FileMediaSource` object is created in XAML, a type converter is invoked to return a `FileMediaSource` instance from a `string`. @@ -374,7 +415,7 @@ Media playback controls implemented by each platform include a volume bar. This A custom volume bar can be implemented using a [`Slider`](xref:Microsoft.Maui.Controls.Slider), as shown in the following example: ```xaml - + - + ``` In this example, the [`Slider`](xref:Microsoft.Maui.Controls.Slider) data binds its `Value` property to the `Volume` property of the `MediaElement`. This is possible because the `Volume` property uses a `TwoWay` binding. Therefore, changing the `Value` property will result in the `Volume` property changing. diff --git a/docs/mvvm/generators/ObservableProperty.md b/docs/mvvm/generators/ObservableProperty.md index 2125ca852..1c24e7bb8 100644 --- a/docs/mvvm/generators/ObservableProperty.md +++ b/docs/mvvm/generators/ObservableProperty.md @@ -100,7 +100,7 @@ partial void OnSelectedItemChanging(ChildViewModel? oldValue, ChildViewModel? ne { if (oldValue is not null) { - oldValue.IsSelected = true; + oldValue.IsSelected = false; } if (newValue is not null)