From e8a7344a6bcc646ec142569eef6ec3c324235af0 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:24:25 -0700 Subject: [PATCH 01/98] CameraView: document that a preview that can't start is reported through ErrorOccurred StartCameraPreview reports a preview that cannot start (no camera, no camera permission, a camera that cannot be opened) through ErrorOccurred on every platform instead of throwing. A first start that fails because of the selected camera follows SelectedCamera; a denied permission stays stopped. On Android a start that failed only for lack of the camera permission starts by itself when the app resumes with the permission granted. Adds the missing ErrorOccurred event to the Events table. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index b43f94fc..2755074d 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -2,7 +2,7 @@ title: CameraView - .NET MAUI Community Toolkit author: bijington description: "The CameraView provides the ability to connect to a camera, display a preview from the camera, take photos, and record videos." -ms.date: 03/17/2026 +ms.date: 10/23/2026 --- # CameraView @@ -189,6 +189,9 @@ In case you plan to record video, request Microphone permissions: var microphonePermissionsRequest = await Permissions.RequestAsync(); ``` +> [!NOTE] +> A `CameraView` can try to start its preview before the camera permission is granted, for example while your app is still asking for it. The failure is reported through the [`ErrorOccurred`](#events) event. On Android, the preview then starts by itself when the app resumes with the permission granted. On the other platforms, call `StartCameraPreview` again once the permission is granted. See [Start preview](#start-preview) for details. + ### Including the XAML namespace [!INCLUDE [XAML usage guidance](../includes/xaml-usage.md)] @@ -640,6 +643,10 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) // Use the Camera field defined above in XAML (``) await Camera.StartCameraPreview(startCameraPreviewTCS.Token); } + catch(OperationCanceledException) + { + // The token was cancelled, or StopCameraPreview was called, before the preview started + } catch(Exception e) { // Handle Exception @@ -648,6 +655,17 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) } ``` +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, and an `InvalidOperationException` when the `CameraView` has no handler yet, for example before it is shown. + +```cs +Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); +``` + +What happens next depends on why the start failed: + +- **The selected camera can't be opened.** The preview stays stopped, but it follows `SelectedCamera`: selecting another camera starts the preview with that camera. This holds until `StopCameraPreview` is called. +- **The camera permission isn't granted.** The preview stays stopped, and selecting another camera doesn't start it. Call `StartCameraPreview` again once the app has the permission. On Android, the preview also starts by itself when the app resumes with the permission granted, for example after the user allowed it in the permission dialog or in the app's settings. This lets a `CameraView` that connects while your app asks for the permission start its preview without another call. A failure of that automatic start is reported through `ErrorOccurred`. Only the last start counts: `StopCameraPreview`, or a later `StartCameraPreview`, cancels it. + ## Stop preview The `CameraView` provides the ability to programmatically stop the preview from the camera. This is possible through both the `StopCameraPreview` method or the `StopCameraPreviewCommand`. @@ -766,6 +784,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) |---------|---------|---------| | `MediaCaptured` | `EventHandler` | Raised when an image is successfully captured. The `MediaCapturedEventArgs` contains a `Media` property of type `Stream` with the captured image data. | | `MediaCaptureFailed` | `EventHandler` | Raised when an image capture fails. The `MediaCaptureFailedEventArgs` contains a `FailureReason` property with the error message. | +| `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. | ## Methods @@ -773,7 +792,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) |---------|---------|---------| | `CaptureImage(CancellationToken)` | `Task` | Captures a single image from the camera. The result is delivered via the `MediaCaptured` event. | | `GetAvailableCameras(CancellationToken)` | `ValueTask>` | Retrieves a list of available camera devices on the device. | -| `StartCameraPreview(CancellationToken)` | `Task` | Starts displaying the camera preview. | +| `StartCameraPreview(CancellationToken)` | `Task` | Starts displaying the camera preview. A preview that can't start is reported through the `ErrorOccurred` event. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the preview started. | | `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. | | `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. | | `StopCameraPreview()` | `void` | Stops displaying the camera preview. | From dc7e62e70a2cd1cd15e18e13caad37aa953366f7 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:25:00 -0700 Subject: [PATCH 02/98] CameraView: rename the catch variable of three samples that collides with the handler's e parameter `catch(Exception e)` inside a method whose EventArgs parameter is named e does not compile (CS0136). Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 2755074d..0be9b0ef 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -460,10 +460,10 @@ async void HandleCaptureButtonTapped(object? sender, EventArgs e) var captureImageCTS = new CancellationTokenSource(TimeSpan.FromSeconds(3)); Stream stream = await Camera.CaptureImage(captureImageCTS.Token); } - catch(Exception e) + catch(Exception ex) { // Handle Exception - Trace.WriteLine(e); + Trace.WriteLine(ex); } } ``` @@ -647,10 +647,10 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) { // The token was cancelled, or StopCameraPreview was called, before the preview started } - catch(Exception e) + catch(Exception ex) { // Handle Exception - Trace.WriteLine(e); + Trace.WriteLine(ex); } } ``` @@ -748,10 +748,10 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) // Use the Camera field defined above in XAML (``) Camera.StopCameraPreview(); } - catch(Exception e) + catch(Exception ex) { // Handle Exception - Trace.WriteLine(e); + Trace.WriteLine(ex); } } ``` From 9c06563a8bb2cad34efa669ac5e78d3be46f231e Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:25:05 -0700 Subject: [PATCH 03/98] CameraView: document that the commands let no exception escape and report each failure once CaptureImageCommand, StartCameraPreviewCommand, StopCameraPreviewCommand, StartVideoRecordingCommand and StopVideoRecordingCommand report a failure once, through MediaCaptureFailed or ErrorOccurred, and a failure that a command reports does not end a pending CaptureImage. Fixes the Commands table, which listed no parameter for the commands that take a CancellationToken and called the Stream of StartVideoRecordingCommand optional, and the return type of CaptureImage. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 0be9b0ef..28cfdbbe 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -446,6 +446,9 @@ The following example shows how to add a `Button` into the application and setup > [!NOTE] > In order to use the image that has been captured the `CameraView` provides the `MediaCaptured` event. +> [!NOTE] +> `CaptureImage` ends with the platform's answer to the capture. A failure that a command reports through the `MediaCaptureFailed` event while the capture waits, for example a video recording that `StartVideoRecordingCommand` can't start, doesn't end the capture. + The following example demonstrates how to use the `CaptureImage` method: > [!NOTE] @@ -772,25 +775,27 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) | Command | Command Parameter | Description | |---------|---------|---------| -| `CaptureImageCommand` | — | Triggers an image capture. The captured image is returned via the `MediaCaptured` event. | -| `StartCameraPreviewCommand` | — | Starts the camera preview display. | -| `StartVideoRecordingCommand` | `Stream` (optional) | Starts video recording. Optionally pass a `Stream` to record into. | -| `StopCameraPreviewCommand` | — | Stops the camera preview display. | -| `StopVideoRecordingCommand` | — | Stops video recording and returns the recorded stream. | +| `CaptureImageCommand` | `CancellationToken` | Triggers an image capture. The captured image is returned via the `MediaCaptured` event. A capture that fails is reported through the `MediaCaptureFailed` event. | +| `StartCameraPreviewCommand` | `CancellationToken` | Starts the camera preview display. A preview that can't start is reported through the `ErrorOccurred` event. | +| `StartVideoRecordingCommand` | `Stream` | Starts video recording into the `Stream`. A recording that can't start is reported through the `MediaCaptureFailed` event. | +| `StopCameraPreviewCommand` | — | Stops the camera preview display. A failure is reported through the `ErrorOccurred` event. | +| `StopVideoRecordingCommand` | `CancellationToken` | Stops video recording. The video is written to the `Stream` that was passed to `StartVideoRecordingCommand`. A failure is reported through the `MediaCaptureFailed` event. | + +The commands let no exception escape. `ICommand.Execute` can't return the task of the work that a command starts, so an exception would reach no caller and end the app. Each failure is reported once, through the event in the table above. A command whose token is cancelled ends without an event, and so does a start that `StopCameraPreview` cancels. ## Events | Event | Type | Description | |---------|---------|---------| | `MediaCaptured` | `EventHandler` | Raised when an image is successfully captured. The `MediaCapturedEventArgs` contains a `Media` property of type `Stream` with the captured image data. | -| `MediaCaptureFailed` | `EventHandler` | Raised when an image capture fails. The `MediaCaptureFailedEventArgs` contains a `FailureReason` property with the error message. | +| `MediaCaptureFailed` | `EventHandler` | Raised when an image capture fails, and when `StartVideoRecordingCommand` or `StopVideoRecordingCommand` fails. The `MediaCaptureFailedEventArgs` contains a `FailureReason` property with the error message. | | `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. | ## Methods | Method | Return Type | Description | |---------|---------|---------| -| `CaptureImage(CancellationToken)` | `Task` | Captures a single image from the camera. The result is delivered via the `MediaCaptured` event. | +| `CaptureImage(CancellationToken)` | `Task` | Captures a single image from the camera and returns it. The image is also delivered via the `MediaCaptured` event. Throws a `CameraException` when the capture fails, for example when the preview hasn't started, and raises the `MediaCaptureFailed` event with the same reason. | | `GetAvailableCameras(CancellationToken)` | `ValueTask>` | Retrieves a list of available camera devices on the device. | | `StartCameraPreview(CancellationToken)` | `Task` | Starts displaying the camera preview. A preview that can't start is reported through the `ErrorOccurred` event. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the preview started. | | `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. | From dff0cab061ddecabb425691ad250b4b53c07832b Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:25:45 -0700 Subject: [PATCH 04/98] CameraView: document that StopCameraPreview cancels a pending start and a camera switch StopCameraPreview cancels a StartCameraPreview, a StartVideoRecording, the start that the view makes when it connects its camera and a camera switch that still wait for the platform, and on Android the restart for a new ImageCaptureResolution and the start that waits for the camera permission. An awaiting caller gets an OperationCanceledException; the commands do not report it as an error. On iOS and Mac Catalyst, StartCameraPreview with an already cancelled token throws an OperationCanceledException and does not start the preview. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 28cfdbbe..3ab5bc30 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -568,6 +568,9 @@ async void StartCameraRecording(object? sender, EventArgs e) } ``` +> [!NOTE] +> `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). + ## Start preview The `CameraView` provides the ability to programmatically start the preview from the camera. This is possible through both the `StartCameraPreview` method or the `StartCameraPreviewCommand`. @@ -759,6 +762,22 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) } ``` +### Cancel pending starts + +`StopCameraPreview` also cancels what is still waiting for the platform to start: + +- A `StartCameraPreview` or `StartVideoRecording` (both overloads) that hasn't completed. +- The start that the `CameraView` makes when it connects to its camera. +- A camera switch, which is a change of `SelectedCamera`. +- On Android, the restart of the preview for a new `ImageCaptureResolution`, and the automatic start that waits for the camera permission. + +None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` again. + +A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when the page closes or the user taps a stop button while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. + +> [!IMPORTANT] +> Catch the `OperationCanceledException` when you await these methods, in particular in an `async void` handler, where an exception that escapes ends the app. Call the start again if you still need the preview or the recording after a `StopCameraPreview` interrupted its start. + ## Properties | Property | Type | Description | Default Value | @@ -778,7 +797,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) | `CaptureImageCommand` | `CancellationToken` | Triggers an image capture. The captured image is returned via the `MediaCaptured` event. A capture that fails is reported through the `MediaCaptureFailed` event. | | `StartCameraPreviewCommand` | `CancellationToken` | Starts the camera preview display. A preview that can't start is reported through the `ErrorOccurred` event. | | `StartVideoRecordingCommand` | `Stream` | Starts video recording into the `Stream`. A recording that can't start is reported through the `MediaCaptureFailed` event. | -| `StopCameraPreviewCommand` | — | Stops the camera preview display. A failure is reported through the `ErrorOccurred` event. | +| `StopCameraPreviewCommand` | — | Stops the camera preview display, and cancels a start that is still in progress. A failure is reported through the `ErrorOccurred` event. | | `StopVideoRecordingCommand` | `CancellationToken` | Stops video recording. The video is written to the `Stream` that was passed to `StartVideoRecordingCommand`. A failure is reported through the `MediaCaptureFailed` event. | The commands let no exception escape. `ICommand.Execute` can't return the task of the work that a command starts, so an exception would reach no caller and end the app. Each failure is reported once, through the event in the table above. A command whose token is cancelled ends without an event, and so does a start that `StopCameraPreview` cancels. @@ -798,9 +817,9 @@ The commands let no exception escape. `ICommand.Execute` can't return the task o | `CaptureImage(CancellationToken)` | `Task` | Captures a single image from the camera and returns it. The image is also delivered via the `MediaCaptured` event. Throws a `CameraException` when the capture fails, for example when the preview hasn't started, and raises the `MediaCaptureFailed` event with the same reason. | | `GetAvailableCameras(CancellationToken)` | `ValueTask>` | Retrieves a list of available camera devices on the device. | | `StartCameraPreview(CancellationToken)` | `Task` | Starts displaying the camera preview. A preview that can't start is reported through the `ErrorOccurred` event. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the preview started. | -| `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. | -| `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. | -| `StopCameraPreview()` | `void` | Stops displaying the camera preview. | +| `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | +| `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | +| `StopCameraPreview()` | `void` | Stops displaying the camera preview, and cancels a start of the preview or of a recording that is still in progress. | | `StopVideoRecording(CancellationToken)` | `Task` | Stops video recording and returns the recorded `Stream`. | ## CameraInfo From 7c711c33f1e2725b403ab115e9a91d71dc16b852 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:25:58 -0700 Subject: [PATCH 05/98] CameraView: note that the Android zoom range is correct in Release apps CameraProvider reads the zoom range of a camera through JavaCast, which trimming keeps. In a Release app, every camera used to report a range of 1 to 1 (#2389), which clamped every ZoomFactor to 1. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 3ab5bc30..a8091b4b 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -244,6 +244,9 @@ The `SelectedCamera` property provides both a `MinimumZoomFactor` and a `Maximum > [!NOTE] > If a value is provided outside of the `MinimumZoomFactor` and `MaximumZoomFactor` the `CameraView` will clamp the value to keep it within the bounds. +> [!NOTE] +> On Android, `MinimumZoomFactor` and `MaximumZoomFactor` come from CameraX for each camera, in Debug and in Release (trimmed) apps. Earlier versions reported a range of 1 to 1 for every camera in Release apps ([#2389](https://github.com/CommunityToolkit/Maui/issues/2389)), which clamped every `ZoomFactor` to 1. + The following example shows how to add a `Slider` into the application and setup the following bindings: - Bind the `Maximum` property of the `Slider` to the `MaximumZoomFactor` of the `SelectedCamera` property. From cb85d3fc9041027e1258ec884cb50aadbfa4c81c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:26:28 -0700 Subject: [PATCH 06/98] MediaElement: document that an exception of an event handler during a Source change is reported through MediaFailed The exception no longer reaches the code that set Source (a breaking change): the MediaElement logs it, applies the source anyway and reports the first exception once through MediaFailed when the change has ended, without setting CurrentState to Failed. Applies to StateChanged, PropertyChanging, PropertyChanged, MediaFailed and, on Android, MediaOpened handlers. Also notes that on Windows a late rate notification no longer undoes a newer Speed. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/MediaElement.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index f603317e..d89e3f93 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -3,7 +3,7 @@ title: MediaElement - .NET MAUI Community Toolkit description: "This article explains how to use MediaElement to play video and audio in a .NET MAUI application." author: jfversluis ms.author: joverslu -ms.date: 02/15/2024 +ms.date: 10/23/2026 --- # MediaElement @@ -326,6 +326,21 @@ The `MediaElementState` enumeration defines the following members: It's generally not necessary to examine the `CurrentState` property when using the `MediaElement` transport controls. However, this property becomes important when implementing your own transport controls. +## Handle exceptions thrown while the source changes + +Changing the `Source` property raises events while the new source is applied: `StateChanged` (for example for `Opening`), `PropertyChanging` and `PropertyChanged` (for example of `CurrentState`, `Duration` and `Position`), `MediaFailed` for a source that can't be applied, and, on Android, `MediaOpened`. The code that sets `Source` is often .NET MAUI itself, from XAML or a binding, so it can't catch an exception that one of these handlers throws. + +For that reason, an exception that one of these handlers throws doesn't reach the code that set `Source`. The `MediaElement` logs it and applies the source anyway. Once the change has ended, it reports the first of these exceptions once through the `MediaFailed` event. The `ErrorMessage` of the `MediaFailedEventArgs` names the type and the message of the exception, and `CurrentState` isn't set to `Failed`, because the source itself didn't fail. An exception that a `MediaFailed` handler throws while it receives that report is only logged. + +```csharp +mediaElement.MediaFailed += (sender, e) => Trace.WriteLine(e.ErrorMessage); +``` + +> [!IMPORTANT] +> An exception thrown by one of these handlers no longer reaches the code that sets `Source`. If your code caught it around the assignment of `Source`, handle the `MediaFailed` event instead. + +This doesn't apply to the events that the player raises after the change has ended, for example `MediaOpened` on iOS, Mac Catalyst and Windows. + ## Implement custom transport controls The transport controls of a media player include the buttons that perform the functions **Play**, **Pause**, and **Stop**. These buttons are generally identified with familiar icons rather than text, and the **Play** and **Pause** functions are generally combined into one button. @@ -447,7 +462,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide | ShouldMute | `bool` | Determines whether the audio is currently muted. This is a bindable property. | `false` | | ShouldShowPlaybackControls | `bool` | Determines whether the platforms playback controls are displayed. This is a bindable property. Note that on iOS and Windows the controls are only shown for a brief period after interacting with the screen. There is no way of keeping the controls visible at all times. | `true` | | Source | `MediaSource?` | The source of the media loaded into the control. | `null` | -| Speed | `double` | Determines the playback speed of the media. This is a bindable property | `1` | +| Speed | `double` | Determines the playback speed of the media. This is a bindable property. On Windows, a late notification of an earlier playback rate no longer undoes a `Speed` that was set after it. | `1` | | MediaHeight | `int` | The height of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | | MediaWidth | `int` | The width of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | | Volume | `double` | Determines the media's volume, which is represented on a linear scale between 0 and 1. This is a bindable property. | `1` | @@ -458,7 +473,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide |---------|---------| | MediaOpened | Occurs when the media stream has been validated and opened. | | MediaEnded | Occurs when the `MediaElement` finishes playing its media. | -| MediaFailed | Occurs when there's an error associated with the media source. | +| MediaFailed | Occurs when there's an error associated with the media source. It is also raised once when an event handler threw an exception while `Source` changed. See [Handle exceptions thrown while the source changes](#handle-exceptions-thrown-while-the-source-changes). | | PositionChanged | Occurs when the `Position` property value has changed. | | SeekCompleted | Occurs when the seek point of a requested seek operation is ready for playback. | From 9ed133397561f7f60d9e6c0e77d6eb93f83a26ab Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:27:27 -0700 Subject: [PATCH 07/98] StatusBarBehavior: remove the UIViewControllerBasedStatusBarAppearance step for iOS, and explain why The toolkit sets the status bar style through the view controllers of the app (on .NET 10 by replacing preferredStatusBarStyle at runtime), which UIKit uses unless Info.plist sets UIViewControllerBasedStatusBarAppearance to false. An app built with the iOS 27 SDK (Xcode 27) ignores UIApplication.SetStatusBarStyle, so the documented key now has to go; the toolkit writes a trace message when it finds the key. Adds a short FAQ entry for it. Also documents that ApplyOn.OnPageNavigatedTo applies nothing for a NavigatedTo that .NET MAUI raises before the page loads, and fixes the type of ApplyOn in the Properties table (StatusBarApplyOn). Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/behaviors/statusbar-behavior.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index 21fbd929..5ce9bb7b 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -2,7 +2,7 @@ title: StatusBarBehavior - .NET MAUI Community Toolkit author: pictos description: "The StatusBarBehavior provides the ability to customize the color and style of a devices status bar." -ms.date: 09/27/2022 +ms.date: 10/23/2026 --- # StatusBarBehavior @@ -17,6 +17,9 @@ The `StatusBarBehavior` applies the color and style values when the properties a > [!NOTE] > If your application changes the status bar appearance on a per page basis then you should make use of the `StatusBarApplyOn.OnPageNavigatedTo` value for the `ApplyOn` property. Otherwise when navigating back the system will preserve the status bar appearance from the page the user navigated from and not to. +> [!NOTE] +> `StatusBarApplyOn.OnPageNavigatedTo` applies nothing when .NET MAUI raises `NavigatedTo` before the page loads. On iOS that is the case when a `TabbedPage` selects the tab of the page and when a `FlyoutPage` shows the page as its `Detail`. With .NET 11, it is also the case when a `NavigationPage` pushes the page, or pops back to it, without animation. + [!INCLUDE [important note on bindings within behaviors](../includes/behavior-bindings.md)] ## Syntax @@ -88,23 +91,36 @@ No changes needed. # [iOS](#tab/ios) -In the _Platforms/iOS/Info.plist_ file, add the following key and value: +No changes needed. UIKit takes the style of the status bar from the view controllers of your app, and the toolkit makes them return the style that you set. This works as long as the _Platforms/iOS/Info.plist_ file doesn't turn view controller-based status bar appearance off. + +If your _Platforms/iOS/Info.plist_ file contains the following entry, which earlier versions of this page told you to add, remove it: ```xml UIViewControllerBasedStatusBarAppearance ``` +> [!IMPORTANT] +> In an app that is built with the iOS 27 SDK (Xcode 27) or later, UIKit ignores `UIApplication.SetStatusBarStyle`. With the key set to `false` the style of the status bar then doesn't change, and the toolkit writes the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false: remove the key from Info.plist_ to the trace output. An app that is built with an earlier SDK still applies the style while the key is `false`, but the key isn't needed there either. + +On .NET 10, the first `LightContent` or `DarkContent` that you set makes the view controllers that don't choose a style of their own return the one you set. `Default` gives every view controller its own style back. A view controller that overrides `preferredStatusBarStyle` keeps its own style, and so does `SFSafariViewController`. + ----- ## Properties |Property |Type |Description | |---------|---------|---------| -| ApplyOn | StatusBarBehavior | When to apply the status bar color and style. | +| ApplyOn | StatusBarApplyOn | When to apply the status bar color and style. | | StatusBarColor | Color | The `Color` name from the Microsoft.Maui.Graphics namespace. | | StatusBarStyle | StatusBarStyle | The style used by statusbar, can be LightContent, DarkContent or Default. | +## Frequently asked questions + +### Why doesn't the status bar style change on iOS? + +Look for the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false_ in the trace output. If it's there, remove the `UIViewControllerBasedStatusBarAppearance` key from the _Platforms/iOS/Info.plist_ file, as described in [Configuration](#configuration). If it isn't, check whether a view controller that overrides `preferredStatusBarStyle` is on screen: it keeps its own style. + ## Examples You can find an example of this behavior in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Behaviors/StatusBarBehaviorPage.xaml). From 5bad9916cd7b4966ed01aa8d107f073463e83901 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:27:56 -0700 Subject: [PATCH 08/98] DialogFragmentService: document how a modal page is laid out below the status bar on Android The dialog of a modal page is laid out like the activity's window since #3189, whatever the status bar color: its content extends behind the system bars and the page receives the status bar inset. A modal page that relied on the old padding must keep clear of the status bar itself, with the safe area. Also corrects the usage: the DialogFragmentService is registered only when SetShouldUseStatusBarBehaviorOnAndroidModalPage(true) is called; the default is false since 2025. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/behaviors/statusbar-behavior.md | 2 ++ .../DialogFragment-customization.md | 24 ++++++++++++++++--- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index 5ce9bb7b..612c9261 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -89,6 +89,8 @@ class MyPage : ContentPage No changes needed. +To apply the status bar color and style of the activity to modal pages as well, see [Dialog Fragment Service](../platform-specific/DialogFragment-customization.md). That page also describes how a modal page is laid out below the status bar. + # [iOS](#tab/ios) No changes needed. UIKit takes the style of the status bar from the view controllers of your app, and the toolkit makes them return the style that you set. This works as long as the _Platforms/iOS/Info.plist_ file doesn't turn view controller-based status bar appearance off. diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index 9d3d84be..d6c70c30 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -2,7 +2,7 @@ title: Dialog Fragment Service - .NET MAUI Community Toolkit author: pictos description: The DialogFragmentService provides an easy way to control the behavior of Modal pages in Android. -ms.date: 02/01/2025 +ms.date: 10/23/2026 --- # Dialog Fragment Service @@ -13,7 +13,7 @@ ms.date: 02/01/2025 ## Usage -By default the .NET MAUI Community Toolkit registers the `DialogFragmentService`, but you can control that as follows +By default the .NET MAUI Community Toolkit doesn't register the `DialogFragmentService`. To let the status bar color and style of the activity apply to modal pages, enable it as follows ```csharp public static class MauiProgram @@ -24,7 +24,7 @@ public static class MauiProgram var builder = MauiApp.CreateBuilder() .UseMauiCommunityToolkit(static options => { - options.SetShouldUseStatusBarBehaviorOnAndroidModalPage(false); + options.SetShouldUseStatusBarBehaviorOnAndroidModalPage(true); }); return builder.Build(); } @@ -33,6 +33,24 @@ public static class MauiProgram There will be cases where you want to fix and customize the `DialogFragment` to match your apps needs, in these scenarios you can create your own implementation of the `IDialogFragmentService` interface and use in combination with other implementations. +## Modal page layout + +When a dialog fragment of the activity starts, such as the one that .NET MAUI shows a modal page in, the `DialogFragmentService` gives the window of its dialog the status bar color of the activity's window and, from Android 11 on, its light status bars appearance. Whatever that color is, the dialog's window is laid out like the toolkit lays out the activity's window: the content of the modal page extends behind the system bars, and the page receives the window insets that it uses to keep clear of them. + +Earlier versions laid the dialog out differently depending on the status bar color. With a color that wasn't transparent, the system padded the content below the status bar. On Android 10 and older, a transparent color gave the page no window insets at all. A modal page that relied on the old padding must now keep clear of the status bar itself, with the safe area. For example, set the `SafeAreaEdges` of the page: + +```csharp +public partial class MyModalPage : ContentPage +{ + public MyModalPage() + { + InitializeComponent(); + + SafeAreaEdges = new SafeAreaEdges(SafeAreaRegions.Container); + } +} +``` + ## Create you own service The following example shows how to present the modals in immersive mode. In order to achieve this we need to have access to the `DialogFragment` and configure its `Window` to behave in the required way. From 5a18c63853eb49dc7ec3d95a7ab2b4724ff97f96 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:28:00 -0700 Subject: [PATCH 09/98] DialogFragmentService: fix three typos Co-Authored-By: Claude Sonnet 5.5 --- .../platform-specific/DialogFragment-customization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index d6c70c30..bbeeb553 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -7,9 +7,9 @@ ms.date: 10/23/2026 # Dialog Fragment Service -.NET 9.0 introduced a breaking change in how modal pages work in Android - they now use a [`DialogFragment`](https://developer.android.com/reference/android/app/DialogFragment). This breaking change resulted in broken functionality within the .NET MAUI Community Toolkit. The `DialogFragmentService` provides a mechanism to fix the breaking changes, +.NET 9.0 introduced a breaking change in how modal pages work in Android - they now use a [`DialogFragment`](https://developer.android.com/reference/android/app/DialogFragment). This breaking change resulted in broken functionality within the .NET MAUI Community Toolkit. The `DialogFragmentService` provides a mechanism to fix the breaking changes. -`IDialogFragmentService` is an interface that allows developers to customize the behavior and appearence of Modal pages in .NET MAUI for Android. The .NET MAUI Community Toolkit provides a default implementation to make sure its features, like `StatusBarColor` will work with the new Modal implementation. +`IDialogFragmentService` is an interface that allows developers to customize the behavior and appearance of Modal pages in .NET MAUI for Android. The .NET MAUI Community Toolkit provides a default implementation to make sure its features, like `StatusBarColor` will work with the new Modal implementation. ## Usage @@ -51,7 +51,7 @@ public partial class MyModalPage : ContentPage } ``` -## Create you own service +## Create your own service The following example shows how to present the modals in immersive mode. In order to achieve this we need to have access to the `DialogFragment` and configure its `Window` to behave in the required way. @@ -60,7 +60,7 @@ For that, first we will need to create a class that implements the `IDialogFragm ```csharp sealed class MyDialogFragmentService : IDialogFragmentService { - // Ommiting other methods + // Omitting other methods public void OnFragmentStarted(AndroidX.Fragment.App.FragmentManager fm, AndroidX.Fragment.App.Fragment f) { From 0aceeee16e0e95fd66c2f8e4b2a5798a7442d4ba Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:28:32 -0700 Subject: [PATCH 10/98] Badge: document that Windows shows a badge only for a packaged app BadgeUpdateManager needs package identity. SetCount of an unpackaged app (the default of the .NET MAUI template) used to end the process with a COMException 0x80070490; it now writes one trace line and does nothing else. Adds a Windows tab to the preconditions, a note on SetCount and a short FAQ entry. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/essentials/badge.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/maui/essentials/badge.md b/docs/maui/essentials/badge.md index 52f74dc5..17963138 100644 --- a/docs/maui/essentials/badge.md +++ b/docs/maui/essentials/badge.md @@ -2,7 +2,7 @@ title: Badge - .NET MAUI Community Toolkit author: VladislavAntonyuk description: The Badge API allows developers to set the app icon badge number on the home screen. -ms.date: 08/09/2023 +ms.date: 10/23/2026 --- # Badge @@ -22,6 +22,10 @@ Additional configuration required to support Android devices. See [Android secti Authorize Badge permission for the app. It is automatically requested. +# [Windows](#tab/windows) + +Windows shows a badge only for an app with package identity, which is a packaged app. An unpackaged app, which is the default of the .NET MAUI template (`None`), doesn't show a badge: `SetCount` writes a line to the trace output and does nothing else. To show a badge, package the app by setting `WindowsPackageType` to `MSIX` in the project file. + # [Tizen](#tab/tizen) Add permissions to `tizen-manifest.xml`: @@ -49,7 +53,7 @@ void SetCount(uint value) |Method |Description | |---------|---------| -| SetCount | Set the badge count. | +| SetCount | Set the badge count. On Windows, only a packaged app can show a badge; an unpackaged app gets a trace line and nothing else. | ## Dependency Registration @@ -92,6 +96,12 @@ public partial class MainPage : ContentPage } ``` +## Frequently asked questions + +### Why doesn't the badge show on Windows? + +Windows shows a badge only for an app with package identity. If your app is unpackaged, which is the default of the .NET MAUI template, `SetCount` writes the message _Unable to set the badge count: Windows shows badges only for apps with package identity, and this app is unpackaged_ to the trace output and does nothing else. It doesn't throw. Package the app by setting `WindowsPackageType` to `MSIX` in the project file. + ## Examples You can find an example of the `Badge` API in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Essentials/BadgePage.xaml). From 1613d09c8d046f8aeee2672fbd11214683d2d925 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:29:21 -0700 Subject: [PATCH 11/98] Expander: document the keyboard and screen reader support Windows: Tab stop, Enter and Space toggle it, UI Automation ExpandCollapse and Invoke. Android: TalkBack announces collapsed or expanded and offers the expand or collapse action. iOS and Mac Catalyst: VoiceOver reads the header as one button, with the expanded state from iOS 18. Documents that HandleHeaderTapped also runs for these activations (no tap parameter, no position except the header center on Windows), the changes that UI tests can see, that UseMauiCommunityToolkit registers a handler for the internal layout of the Expander, and that an implicit Grid Style does not reach it. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/Expander.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index 2b50391e..45eeddc5 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -2,7 +2,7 @@ title: Expander - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Expander control provides an expandable container to host any content." -ms.date: 11/08/2022 +ms.date: 10/23/2026 --- # Expander @@ -11,10 +11,10 @@ The `Expander` control provides an expandable container to host any content. The ## Header -This `Header` property can be provided with any view to allow for full customization. The `Header` will always be visible and interacting with it (clicking or tapping) will show/collapse the `Content`. +This `Header` property can be provided with any view to allow for full customization. The `Header` will always be visible and interacting with it (clicking, tapping, or using the keyboard or a screen reader) will show/collapse the `Content`. See [Accessibility](#accessibility). > [!NOTE] -> It is not recommended to place controls inside the header that allow user interaction. +> It is not recommended to place controls inside the header that allow user interaction. VoiceOver doesn't read a header that holds a control as one button, so that it can still reach the control. ## Content @@ -23,6 +23,9 @@ This is the main content that will show when the `Header` property is interacted > [!NOTE] > `Expander` may work unexpectedly if it is placed inside `ListView` or `CollectionView`. However, it can be controlled with the custom implementation by setting `public Action? HandleHeaderTapped { get; set; }`. This action is executed each time the header tapped. Please pay attention, by changing this action you may receive different behavior in `CollectionView` and `ListView` on all platforms. +> [!NOTE] +> The `Expander` lays out its `Header` and `Content` in a `Grid` of its own. An implicit `Style` for `Grid`, for example one in _App.xaml_, doesn't apply to that `Grid` unless the `Style` sets `ApplyToDerivedTypes`. Even then the `Background` and `BackgroundColor` of that `Grid` stay `null`, so the background of the `Expander` shows behind the `Header` and the `Content`. + ![Screenshot of an Expander in collapsed and expanded states](../images/views/Expander.gif "Expander showing in MacCatalyst") ## Basic usage @@ -124,6 +127,30 @@ Content = new Expander }.CenterHorizontal(); ``` +## Accessibility + +Keyboard and screen reader users can expand and collapse an `Expander` through its `Header` whenever a tap on the `Header` can: while the `Header` is visible, enabled and not input transparent. While a tap can't toggle the `Expander`, it offers no action to the keyboard or to a screen reader. + +|Platform |Behavior | +|---------|---------| +| Windows | The `Expander` is a Tab stop. Enter toggles it when it is pressed and Space when it is released, like a `Button`. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | +| Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand or collapse action in its actions menu. The click of a `TapGestureRecognizer` on the `Header` stays available. | +| iOS and Mac Catalyst | VoiceOver reads the whole `Header` as one button that a double tap toggles. The element has the button trait, and the header trait when the `Header` is a heading. Its label, hint and `AutomationId` come from the `Header`. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A `Header` that holds a control, such as a `Button`, a `Switch` or an `Entry`, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the `Expander` for it. A `Header` with another `TapGestureRecognizer` lets VoiceOver tap it, so that every recognizer runs. | + +Every activation from the keyboard or from assistive technology goes through the same code as a tap, so `IsExpanded`, `Command` and `CommandParameter`, `ExpandedChanged` and `HandleHeaderTapped` behave as for a tap. In a `CollectionView` on Windows, such an activation still resizes the item that holds the `Expander`. + +> [!IMPORTANT] +> `HandleHeaderTapped` also runs when the `Header` is activated without a tap: from the keyboard or by UI Automation on Windows, by the expand or collapse action of TalkBack on Android, and by VoiceOver on iOS and Mac Catalyst. For these activations `TappedEventArgs.Parameter` is `null`, and `TappedEventArgs.GetPosition` returns the center of the `Header` on Windows and `null` on Android, iOS and Mac Catalyst. A custom `HandleHeaderTapped` that assumes a pointer position must handle `null`. + +The `UseMauiCommunityToolkit` method registers a handler for the layout of the `Expander`, which provides this on Windows, iOS and Mac Catalyst. A handler that your app registers for `Grid` no longer applies to the `Grid` of the `Expander`. Changes to `LayoutHandler.Mapper` still apply. + +### UI tests + +The accessibility support changes what UI automation finds: + +- **Windows:** a button with the class name `Expander`, named after the `Header`, wraps the `Header` and the `Content` in the UI Automation tree. A test that finds the `Header` by name can match this element first, and its bounds include the expanded `Content`. The element of the `Header` itself, with its `AutomationId`, is still there as a child. +- **iOS and Mac Catalyst:** the views inside a `Header` are no longer separate accessibility elements, unless the `Header` holds a control. The element of the `Header` has the `AutomationId` of the `Header`, so a query for a view inside a layout `Header` by its own `AutomationId`, for example with XCUITest or Appium, no longer finds it. + ## Properties |Property |Type |Description | @@ -142,7 +169,7 @@ The `ExpandDirection` enumeration defines the following members: | `Down` | Indicates that the `Expander` content is under the header. | | `Up` | Indicates that the `Expander` content is above the header. | -The `Expander` control also defines a `ExpandedChanged` event that's fired when the `Expander` header is tapped. +The `Expander` control also defines a `ExpandedChanged` event that's fired when the `Expander` header is tapped, or activated from the keyboard or by assistive technology. ### ExpandedChangedEventArgs From 39ab9c1e8bcce91ff8d012b52f9f110059ef460d Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:29:56 -0700 Subject: [PATCH 12/98] SemanticOrderView: document the platform behavior, and that on Windows ViewOrder sets the Tab order On Windows, ViewOrder sets the keyboard Tab order of the views, and Narrator's scan order follows the visual tree. On Android the order applies from Android 5.1 (API 22); on iOS and Mac Catalyst the views of ViewOrder are the first accessibility elements. Views that are not in ViewOrder stay accessible. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/semantic-order-view.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index dbeb6e1b..c9ecb4c9 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -2,12 +2,12 @@ title: SemanticOrderView - .NET MAUI Community Toolkit author: bijington description: The SemanticOrderView provides the ability to control the order of VisualElements for screen readers and improve the Accessibility of an application. -ms.date: 02/28/2023 +ms.date: 10/23/2026 --- # SemanticOrderView -The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers and improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. +The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers, and on Windows the keyboard Tab order, and improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. ## Using the SemanticOrderView @@ -34,7 +34,7 @@ The following example shows how the `SemanticOrderView` can change the order in ``` -To over come that, in the code behind file we can change the order that will be used by the device's screen reader as follows: +To overcome that, in the code behind file we can change the order that will be used by the device's screen reader as follows: ```csharp using System.Collections.Generic; @@ -54,6 +54,16 @@ public partial class SemanticOrderViewPage : ContentPage With this, we tell the `SemanticOrderView` that the "proper" order for these controls, when accessed through screen reader software, is to first focus the `TitleLabel` and then `DescriptionLabel`. +## Platform behavior + +The views that aren't in `ViewOrder` stay accessible on every platform. + +|Platform |Behavior | +|---------|---------| +| iOS and Mac Catalyst | The views of `ViewOrder` are the first accessibility elements of the `SemanticOrderView`, in that order. Assistive technologies visit the other views after them, in the order of the view hierarchy. | +| Android | On Android 5.1 (API 22) or later, the order of `ViewOrder` determines how TalkBack traverses the views. On earlier versions the order isn't applied, and a message is written to the trace output. | +| Windows | `ViewOrder` sets the keyboard Tab order of the views. It doesn't change the order in which Narrator reads them, which follows the visual tree. | + ## Examples You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/SemanticOrderView/). From 3cd9cd5ec360dcf08718796bc1e1ae7d25df969d Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:30:00 -0700 Subject: [PATCH 13/98] SemanticOrderView: document how the Windows Tab order is built (W3-R3a) The views of ViewOrder that the container holds come first among its own Tab stops, followed by the rest of its content, so Tab reaches the controls above the container before them and the controls below it after them. A view inside a control within the container (a ScrollView), or outside the container, gets a TabIndex instead. This documents the Windows mechanism of the semanticorder branch of push 3; drop this commit if that change moves out of #3344. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/semantic-order-view.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index c9ecb4c9..cb673616 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -64,6 +64,8 @@ The views that aren't in `ViewOrder` stay accessible on every platform. | Android | On Android 5.1 (API 22) or later, the order of `ViewOrder` determines how TalkBack traverses the views. On earlier versions the order isn't applied, and a message is written to the trace output. | | Windows | `ViewOrder` sets the keyboard Tab order of the views. It doesn't change the order in which Narrator reads them, which follows the visual tree. | +On Windows, the views of `ViewOrder` that the `SemanticOrderView` holds come first among the Tab stops of the `SemanticOrderView`, in the order of `ViewOrder`, followed by the rest of its content in the order of the visual tree. The Tab key reaches the controls above the `SemanticOrderView` before these views, and the controls below it after them. A view of `ViewOrder` that is inside a control within the `SemanticOrderView`, such as a `ScrollView`, or outside of the `SemanticOrderView`, gets a `TabIndex` instead. That `TabIndex` orders it among the Tab stops of the nearest control that holds it. + ## Examples You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/SemanticOrderView/). From d0bf7a325d6a2cd32605af6241363177b8dcce00 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:30:48 -0700 Subject: [PATCH 14/98] AvatarView: document that an empty or failed ImageSource shows the Text, and that CornerRadius needs 0 or more An empty ImageSource (IsEmpty), or one that fails to load, shows the Text on every platform; iOS, Mac Catalyst and Windows used to show an empty circle. Set Text to an empty string for a blank circle. .NET MAUI's RoundRectangle draws a negative CornerRadius as notched shapes. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/AvatarView.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/AvatarView.md b/docs/maui/views/AvatarView.md index 7d889387..a1862e36 100644 --- a/docs/maui/views/AvatarView.md +++ b/docs/maui/views/AvatarView.md @@ -2,7 +2,7 @@ title: AvatarView - .NET MAUI Community Toolkit author: GeorgeLeithead description: "The `AvatarView` is a control for displaying a user's avatar image or their initials." -ms.date: 07/11/2022 +ms.date: 10/23/2026 --- # AvatarView @@ -57,8 +57,8 @@ partial class MyPage : ContentPage | BackgroundColor | `Color` | The `BackgroundColor` property is a Color that determines the background color of the control. If unset, the background will be the default Color object, which renders as White. | | BorderColor | `Color` | The `BorderColor` property is a Color that determines the border color of the control. If unset, the border will be the default Color object, which renders as Black. | | BorderWidth | `double` | The `BorderWidth` property is a double that determines the rendered width of the control border. If unset, the border width will be the default, which renders as 1.0. | -| CornerRadius | `CornerRadius` | The `CornerRadius` property is a CornerRadius that determines the shape of the control. It 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 control. This property is measured in device-independent units. If unset, the corner radius will be the default CornerRadius object, which renders as 24. | -| ImageSource | `ImageSource` | The `ImageSource` property is an ImageSource that determines the image of the control. It can be set to an image retrieved from a file, embedded resource, URI, or stream. If unset, the control will render the `Text` property. | +| CornerRadius | `CornerRadius` | The `CornerRadius` property is a CornerRadius that determines the shape of the control. It 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 control. This property is measured in device-independent units. If unset, the corner radius will be the default CornerRadius object, which renders as 24. Use radii of 0 or more: .NET MAUI draws a negative radius as notched shapes. | +| ImageSource | `ImageSource` | The `ImageSource` property is an ImageSource that determines the image of the control. It can be set to an image retrieved from a file, embedded resource, URI, or stream. If unset, empty, or the image fails to load, the control will render the `Text` property. | | Padding | `Thickness` | The `Padding` property is a Thickness that represents the distance between control border and the `Text` or `ImageSource`. If unset, the padding will be the default Thickness object, which is 1. | | Text | `string` | The `Text` property is a string that determines the text of the control. If unset, the text will be the default, which renders as '?'. | | TextColor | `Color` | The `TextColor` property is a Color that determines the text color of the control. If unset, the text will be the default Colour object. | @@ -141,6 +141,9 @@ AvatarView avatarView = new() The `CornerRadius` property is a CornerRadius that determines the shape of the control. It 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 control. +> [!NOTE] +> Use radii of 0 or more. The `RoundRectangle` of .NET MAUI, which draws the shape of the `AvatarView`, draws a negative radius as notched shapes. + The following example sets the corner radius of an `AvatarView` such that each of the four corners have a specified radius: ```xaml @@ -213,6 +216,8 @@ AvatarView avatarView = new() }; ``` +While an `ImageSource` is set, the `AvatarView` shows the image instead of its `Text`. When the `ImageSource` is empty, which means that its `IsEmpty` property is `true`, for example a `UriImageSource` without a `Uri`, or when the image fails to load, for example because a URL can't be reached, the `AvatarView` shows its `Text` again. This holds on every platform, and until the `ImageSource` is no longer empty and loads, or another `ImageSource` is set. To show a blank circle instead, set `Text` to an empty string. + ## Set padding The `Padding` property is a Thickness that represents the distance between control border and the `Text` or `ImageSource`. From dfe695e3a0358589d50a3ac838197b3bd3afe3ea Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:30:48 -0700 Subject: [PATCH 15/98] AvatarView: correct the documented defaults of BorderColor and BackgroundColor The default border color is white (AvatarViewDefaults.BorderColor), not black, and the control sets no background color of its own. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/AvatarView.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maui/views/AvatarView.md b/docs/maui/views/AvatarView.md index a1862e36..0950ba62 100644 --- a/docs/maui/views/AvatarView.md +++ b/docs/maui/views/AvatarView.md @@ -54,8 +54,8 @@ partial class MyPage : ContentPage | Property | Type | Description | |---|---|---| -| BackgroundColor | `Color` | The `BackgroundColor` property is a Color that determines the background color of the control. If unset, the background will be the default Color object, which renders as White. | -| BorderColor | `Color` | The `BorderColor` property is a Color that determines the border color of the control. If unset, the border will be the default Color object, which renders as Black. | +| BackgroundColor | `Color` | The `BackgroundColor` property is a Color that determines the background color of the control. If unset, the control has no background color. | +| BorderColor | `Color` | The `BorderColor` property is a Color that determines the border color of the control. If unset, the border will be the default Color object, which renders as White. | | BorderWidth | `double` | The `BorderWidth` property is a double that determines the rendered width of the control border. If unset, the border width will be the default, which renders as 1.0. | | CornerRadius | `CornerRadius` | The `CornerRadius` property is a CornerRadius that determines the shape of the control. It 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 control. This property is measured in device-independent units. If unset, the corner radius will be the default CornerRadius object, which renders as 24. Use radii of 0 or more: .NET MAUI draws a negative radius as notched shapes. | | ImageSource | `ImageSource` | The `ImageSource` property is an ImageSource that determines the image of the control. It can be set to an image retrieved from a file, embedded resource, URI, or stream. If unset, empty, or the image fails to load, the control will render the `Text` property. | From e617af7b31e5847867845417820f6e308c9e29b6 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 16 Oct 2026 11:49:29 -0700 Subject: [PATCH 16/98] Enhance Popup documentation with theming details Added theming information and customization options for popups. --- docs/maui/views/Popup.md | 47 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index 76291f95..fc095568 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -243,6 +243,7 @@ The `DefaultPopupSettings` provided will be applied as the default value for eve { CanBeDismissedByTappingOutsideOfPopup = true, BackgroundColor = Colors.Orange, + BackgroundColorDark = Colors.Black, HorizontalOptions = LayoutOptions.End, VerticalOptions = LayoutOptions.Start, Margin = 72, @@ -260,6 +261,52 @@ The `DefaultPopupSettings` provided will be applied as the default value for eve }) ``` +## Theming + +A `Popup`'s background color follows the app's `AppTheme` — it responds to `Application.UserAppTheme`. The default background is: + +| Theme | Default background | Set via | +| ----- | ------------------ | ------- | +| Light | `Colors.White` | `DefaultPopupSettings.BackgroundColor` | +| Dark | `Colors.Black` | `DefaultPopupSettings.BackgroundColorDark` | + +Because the background is theme-aware, a `Popup` whose content uses `AppThemeBinding` (for example a `Label` bound to `Light=Black, Dark=White`) stays readable in **both** themes, instead of rendering white-on-white — and therefore invisible — in dark mode. + +### Overriding the theme-aware background + +Override either color through `SetPopupDefaults`: + +```cs +options.SetPopupDefaults(new DefaultPopupSettings +{ + BackgroundColor = Colors.White, // light theme + BackgroundColorDark = Colors.Black, // dark theme +}); +``` + +> [!TIP] +> When a popup is built from a plain `View` (for example `this.ShowPopupAsync(new ContentView())`), the popup keeps the theme-aware background as long as that view does not set its own non-transparent `BackgroundColor`. A background-less view is therefore visible in dark mode. + +### Customizing a popup on each presentation (OnInitializing) + +`DefaultPopupSettings.OnInitializing` is an optional `Action` callback that runs **each time a `Popup` is presented** — that is, when the `PopupPage` hosting it is created. It runs after the popup and its content are fully built, but before the popup is parented on the page. + +Unlike a constructor-time hook (which runs before XAML or a derived constructor's content exists), `OnInitializing` runs at presentation time, so the popup's `Content` is already available. Use it to customize a popup per presentation, for example adjusting its `BackgroundColor`: + +```cs +options.SetPopupDefaults(new DefaultPopupSettings +{ + OnInitializing = popup => + { + // Runs once per presentation, with popup.Content already available. + popup.BackgroundColor = Colors.Orange; + }, +}); +``` + +> [!CAUTION] +> If the `OnInitializing` callback throws, the popup is **not** presented — the exception propagates before the popup is parented. + ## Events The `Popup` class provides the following events that can be subscribed to. From 131ad46013c46ae86009464e16dda518d9ed60bf Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:32:29 -0700 Subject: [PATCH 17/98] Popup: document which value is used when popup settings, options, Styles and OnInitializing set the same property Adds "Which value is used" to Setting Popup Defaults, from the XML docs of Popup, DefaultPopupSettings, PopupOptions and Options and the probes that checked them: DefaultPopupSettings and DefaultPopupOptionsSettings are defaults that a Style, a value on the Popup or PopupOptions, or a binding override; OnInitializing is not a default and beats a Style; a Margin of 0 or Fill options are displayed with the DefaultPopupSettings value; the default background color is not the BackgroundColor of the Popup, which stays null; the Popup created for a View binds Margin, options, Background, BackgroundColor and Padding to the View; a tap outside or the Android back button dismisses the Popup only while the Popup and the PopupOptions both allow it. Also corrects the tip about a View's background in the theming section: a View with a Background or a BackgroundColor of any kind, Transparent included, keeps it. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/Popup.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index fc095568..769383af 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -2,7 +2,7 @@ title: Popup - .NET MAUI Community Toolkit author: bijington description: The Popup view allows developers to build their own custom UI and present it to their users. -ms.date: 04/12/2022 +ms.date: 10/23/2026 --- # Popup @@ -176,7 +176,7 @@ public class MyPage : ContentPage ### 2. Tapping outside of the Popup -By default a user can tap outside of the `Popup` to dismiss it. This can be controlled through the use of the `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` property. Setting this property to `false` will prevent a user from being able to dismiss the `Popup` by tapping outside of it. See [PopupOptions](./popup/popup-options.md) for more details. +By default a user can tap outside of the `Popup` to dismiss it. This can be controlled through the use of the `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` property, or the `CanBeDismissedByTappingOutsideOfPopup` property of the `Popup`. Setting either property to `false` will prevent a user from being able to dismiss the `Popup` by tapping outside of it: the `Popup` is dismissed only while both are `true`. See [PopupOptions](./popup/popup-options.md) for more details. ## Lifecycle behavior @@ -234,7 +234,7 @@ The `PageOverlayColor`, `Shape`, `Shadow` can all be customized for Popup. See [ To override the default values for every `Popup` in your app, you can call `.SetPopupDefaults()` and `.SetPopupOptionsDefaults()` when initializing .NET MAUI Community Toolkit. -The `DefaultPopupSettings` provided will be applied as the default value for every `Popup` in your app, and the `DefaultPopupOptionsSettings` will be applied as the default value for `PopupOptions` every time `.ShowPopup()` is called. +The `DefaultPopupSettings` provided apply to every `Popup` in your app. The `DefaultPopupOptionsSettings` provided are the options of every `Popup` that is shown without `PopupOptions`, and the initial values of every `PopupOptions` that you create. A value that you set on a `Popup` or a `PopupOptions` takes precedence over them: see [Which value is used](#which-value-is-used). ```cs .UseMauiCommunityToolkit(static options => @@ -261,6 +261,22 @@ The `DefaultPopupSettings` provided will be applied as the default value for eve }) ``` +### Which value is used + +The settings above are defaults, and a value that you set on a `Popup` or a `PopupOptions` takes precedence over them. From the lowest to the highest precedence: + +1. **The defaults.** `DefaultPopupSettings` provides the default value of `Margin`, `Padding`, `HorizontalOptions`, `VerticalOptions` and `CanBeDismissedByTappingOutsideOfPopup` of every `Popup`. `DefaultPopupOptionsSettings` provides the options of a `Popup` that is shown with `null` options, and the initial values of every `PopupOptions` that you create. +2. **A `Style`** of the `Popup`: explicit, implicit, `StyleClass` or `DynamicResource`. The defaults are default values, not local values, so a `Style` can set these properties. +3. **A value that you set on the `Popup` or the `PopupOptions`**, in XAML or in code, or a binding. +4. **[`OnInitializing`](#customizing-a-popup-on-each-presentation-oninitializing).** It isn't a default value. It runs each time a `Popup` is shown, after the `Popup` and its content are built. A value that it sets on the `Popup` replaces the value that was set before, for example in XAML, and takes precedence over a `Style`. + +A few cases don't follow that order: + +- **Margin, HorizontalOptions and VerticalOptions.** A `Popup` whose `Margin` is 0 on every side, or whose `HorizontalOptions` or `VerticalOptions` is `LayoutOptions.Fill`, is displayed with the value of `DefaultPopupSettings` instead. The properties of the `Popup` keep their value. +- **Background.** `DefaultPopupSettings.BackgroundColor` isn't the default value of `BackgroundColor`. The `BackgroundColor` of a `Popup` is `null` until a value, a binding or a `Style` sets it. The color fills the background of a `Popup` that has neither a `BackgroundColor` nor a `Background`. When the `Popup` has a `Background`, that brush is drawn instead. +- **A view that isn't a Popup.** When you show a view that isn't a `Popup`, the `Popup` that the toolkit creates for it binds its `Margin`, `HorizontalOptions`, `VerticalOptions`, `Background`, `BackgroundColor` and, when the view has a `Padding`, its `Padding` to those of the view, so a `Style` can't set them. A margin or padding of the view that is 0 on every side gives the `Popup` the `Margin` or `Padding` of `DefaultPopupSettings`. +- **Dismissing the popup.** A tap outside of the `Popup`, or the hardware back button on Android, dismisses the `Popup` only while both `Popup.CanBeDismissedByTappingOutsideOfPopup` and `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` are `true`. While either is `false`, both do nothing. + ## Theming A `Popup`'s background color follows the app's `AppTheme` — it responds to `Application.UserAppTheme`. The default background is: @@ -285,7 +301,7 @@ options.SetPopupDefaults(new DefaultPopupSettings ``` > [!TIP] -> When a popup is built from a plain `View` (for example `this.ShowPopupAsync(new ContentView())`), the popup keeps the theme-aware background as long as that view does not set its own non-transparent `BackgroundColor`. A background-less view is therefore visible in dark mode. +> When a popup is built from a plain `View` (for example `this.ShowPopupAsync(new ContentView())`), the popup keeps the theme-aware background as long as that view sets neither a `BackgroundColor` nor a `Background` of its own. A background-less view is therefore visible in dark mode. ### Customizing a popup on each presentation (OnInitializing) From 19422188839633148453f1444f7a816800710ec9 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:32:56 -0700 Subject: [PATCH 18/98] PopupOptions: document the dismissal rule and where unset options come from A tap outside or the Android back button dismisses a Popup only while the PopupOptions and the Popup both allow it. The options that are not set start with DefaultPopupOptionsSettings, which also are the options of a Popup that is shown without PopupOptions. Also fixes the "Disable the Popup Shadow" text, which told the reader to set Shape, and two unfinished or garbled sentences. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/popup/popup-options.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/maui/views/popup/popup-options.md b/docs/maui/views/popup/popup-options.md index 86b6ce4e..e392e26b 100644 --- a/docs/maui/views/popup/popup-options.md +++ b/docs/maui/views/popup/popup-options.md @@ -2,7 +2,7 @@ title: PopupOptions - .NET MAUI Community Toolkit author: bijington description: The PopupOptions class provides the ability to customize the appearance and behavior of the Popup. -ms.date: 05/19/2025 +ms.date: 10/23/2026 --- # PopupOptions - Customizing the popup behavior and appearance @@ -11,9 +11,11 @@ The `PopupOptions` class provides the ability to customize the appearance and be All of the examples in this page make use of the `SimplePopup` example that is covered at [`Popup`](../popup.md). +The options that you don't set start with the values of `DefaultPopupOptionsSettings`, which you can change with `SetPopupOptionsDefaults`. A `Popup` that is shown without `PopupOptions` uses these values too. See [Setting Popup Defaults](../popup.md#setting-popup-defaults) for how they combine with the other settings of a `Popup`. + ## Controlling whether the user can dismiss the Popup -`PopupOptions` provides the `CanBeDismissedByTappingOutsideOfPopup` property which can control the whether the user can tap or click outside of the Popup bounds to dismiss the currently displayed Popup. This is `true` by default. The following example shows how to prevent a user from being able to dismiss the Popup. +`PopupOptions` provides the `CanBeDismissedByTappingOutsideOfPopup` property which can control whether the user can tap or click outside of the Popup bounds to dismiss the currently displayed Popup. This is `true` by default. The following example shows how to prevent a user from being able to dismiss the Popup. ```csharp await this.ShowPopupAsync(new SimplePopup(), new PopupOptions @@ -22,6 +24,9 @@ await this.ShowPopupAsync(new SimplePopup(), new PopupOptions }); ``` +> [!NOTE] +> A tap outside of the `Popup`, or the hardware back button on Android, dismisses the `Popup` only while both `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` and the `CanBeDismissedByTappingOutsideOfPopup` property of the `Popup` are `true`. While either is `false`, both do nothing. + > [!NOTE] > It is possible to cache `PopupOptions` to reuse on future navigation actions or with other popups that share the same configuration, that would prevent unnecessary allocations. @@ -38,7 +43,7 @@ await this.ShowPopupAsync(new SimplePopup(), new PopupOptions ![Popup page overlay](../../images/views/popup/popup-page-overlay-opaque.png "Popup rendering with an opaque orange background") -The above `Popup` renders with an opaque background, to control the opacity modify the alpha property of a `Color`. The following example shows how to +The above `Popup` renders with an opaque background, to control the opacity modify the alpha property of a `Color`. The following example shows how to set the `PageOverlayColor` to orange with an alpha of 0.5. ```csharp await this.ShowPopupAsync(new SimplePopup(), new PopupOptions @@ -103,7 +108,7 @@ For more details on how to customize the `Shadow` property see [.NET MAUI Shadow ### Disable the Popup Shadow -In order to disable the border on a Popup, simply set the `Shape` property to `null`. The following example shows how to achieve this +In order to disable the shadow on a Popup, simply set the `Shadow` property to `null`. The following example shows how to achieve this ```csharp await this.ShowPopupAsync(new SimplePopup(), new PopupOptions @@ -118,7 +123,7 @@ await this.ShowPopupAsync(new SimplePopup(), new PopupOptions |Property |Type |Description | |---------|---------|---------| -| `CanBeDismissedByTappingOutsideOfPopup` | `bool` | Gets or sets a value indicating whether the popup can be dismissed by tapping outside of the Popup. On Android - when false the hardware back button is disabled. | +| `CanBeDismissedByTappingOutsideOfPopup` | `bool` | Gets or sets a value indicating whether the popup can be dismissed by tapping outside of the Popup. On Android - when false the hardware back button is disabled. The popup is dismissed only while this property and the `CanBeDismissedByTappingOutsideOfPopup` property of the `Popup` are both `true`. | | `OnTappingOutsideOfPopup` | `Action` | Gets or sets the `Action` to be executed when the user taps outside the `Popup`. | | `PageOverlayColor` | `Color` | Gets or sets the `Color` of the overlay behind the `Popup`. | | `Shape` | `Shape` | Gets or sets the border shape for the `Popup`. Set this to `null` to remove any border styling. | From 7d969876249f03fc6e2916343874dba87174132b Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:33:16 -0700 Subject: [PATCH 19/98] Options: add SetPopupDefaults, SetPopupOptionsDefaults and SetShouldUseStatusBarBehaviorOnAndroidModalPage The options page lists only three of the options, and the popup defaults and the modal page option of the status bar are documented on other pages. Adds a short entry for each that links to the page with the details. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/options.md | 55 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/maui/options.md b/docs/maui/options.md index 861d2a3e..c73c0d03 100644 --- a/docs/maui/options.md +++ b/docs/maui/options.md @@ -2,7 +2,7 @@ title: Options - .NET MAUI Community Toolkit author: VladislavAntonyuk description: CommunityToolkit.Maui.Options allows to customize the CommunityToolkit.Maui. -ms.date: 09/14/2022 +ms.date: 10/23/2026 --- # CommunityToolkit.Maui.Options @@ -105,4 +105,55 @@ builder.UseMauiCommunityToolkit(options => { options.SetShouldSuppressExceptionsInBehaviors(true); }) -``` \ No newline at end of file +``` + +## SetPopupDefaults + +Sets the default settings of every `Popup`: its `Margin`, `Padding`, `HorizontalOptions`, `VerticalOptions` and `CanBeDismissedByTappingOutsideOfPopup`, the background color for the light and the dark theme, and the `OnInitializing` callback that runs each time a `Popup` is shown. A value that you set on a `Popup` takes precedence over the default values. See [Setting Popup Defaults](views/Popup.md#setting-popup-defaults) for the settings and for which value is used. + +### Example + +```csharp +var builder = MauiApp.CreateBuilder(); +builder.UseMauiCommunityToolkit(options => +{ + options.SetPopupDefaults(new DefaultPopupSettings + { + Margin = 72, + BackgroundColor = Colors.Orange + }); +}) +``` + +## SetPopupOptionsDefaults + +Sets the default `PopupOptions`: the options of a `Popup` that is shown without `PopupOptions`, and the initial values of every `PopupOptions` that you create. See [Setting Popup Defaults](views/Popup.md#setting-popup-defaults). + +### Example + +```csharp +var builder = MauiApp.CreateBuilder(); +builder.UseMauiCommunityToolkit(options => +{ + options.SetPopupOptionsDefaults(new DefaultPopupOptionsSettings + { + PageOverlayColor = Colors.Orange + }); +}) +``` + +## SetShouldUseStatusBarBehaviorOnAndroidModalPage + +When set to `true`, the toolkit registers the `DialogFragmentService`, which gives the dialog of a modal page on Android the status bar color and style of the activity, and lays it out like the activity's window. See [Dialog Fragment Service](platform-specific/DialogFragment-customization.md). + +Default value is `false`. + +### Example + +```csharp +var builder = MauiApp.CreateBuilder(); +builder.UseMauiCommunityToolkit(options => +{ + options.SetShouldUseStatusBarBehaviorOnAndroidModalPage(true); +}) +``` From 3a7de21f0958cc10a593e93402f249278b62afad Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:33:42 -0700 Subject: [PATCH 20/98] Keyboard: document that HideKeyboardAsync works inside a Popup on Android and when the behaviors dismiss the keyboard HideKeyboardAsync hides the keyboard on Android through the window of the focused view, so it also works for an input inside a Popup or a modal page, which have a window of their own. MaxLengthReachedBehavior and UserStoppedTypingBehavior dismiss the keyboard, and remove the focus from the InputView, only while the InputView has the focus; the keyboard of another input stays open. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/behaviors/maximum-length-reached-behavior.md | 6 +++--- docs/maui/behaviors/user-stopped-typing-behavior.md | 6 ++++-- docs/maui/extensions/keyboard-extensions.md | 6 ++++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/maui/behaviors/maximum-length-reached-behavior.md b/docs/maui/behaviors/maximum-length-reached-behavior.md index d36ece04..54cb5af4 100644 --- a/docs/maui/behaviors/maximum-length-reached-behavior.md +++ b/docs/maui/behaviors/maximum-length-reached-behavior.md @@ -2,14 +2,14 @@ title: MaxLengthReachedBehavior - .NET MAUI Community Toolkit author: bijington description: "The MaxLengthReachedBehavior is a behavior that allows the user to trigger an action when a user has reached the maximum length allowed on an InputView." -ms.date: 03/02/2022 +ms.date: 10/23/2026 --- # MaxLengthReachedBehavior The `MaxLengthReachedBehavior` is a `Behavior` that allows the user to trigger an action when a user has reached the maximum length allowed on an `InputView`. It can either trigger a `Command` or an event depending on the user's preferred scenario. Both the `Command` and event will include the resulting text of the `InputView`. -Additionally it is possible to dismiss the keyboard when the maximum length is reached via the `ShouldDismissKeyboardAutomatically` property which defaults to `false`. +Additionally it is possible to dismiss the keyboard when the maximum length is reached via the `ShouldDismissKeyboardAutomatically` property which defaults to `false`. Dismissing the keyboard also removes the focus from the `InputView`. The keyboard is only dismissed while the `InputView` has the focus, so the keyboard of another view that the user types in stays open. [!INCLUDE [important note on bindings within behaviors](../includes/behavior-bindings.md)] @@ -104,7 +104,7 @@ class MaxLengthReachedBehaviorPage : ContentPage |Property |Type |Description | |---------|---------|---------| | `Command` | [ICommand](xref:System.Windows.Input.ICommand) | The command that is executed when the user has reached the maximum length. The parameter of the command will contain the `Text` of the `InputView`. | -| `ShouldDismissKeyboardAutomatically` | `bool` | Indicates whether or not the keyboard should be dismissed automatically when the maximum length is reached. | +| `ShouldDismissKeyboardAutomatically` | `bool` | Indicates whether or not the keyboard should be dismissed automatically when the maximum length is reached. Dismissing the keyboard also removes the focus from the `InputView`, and only happens while the `InputView` has the focus. | ## Events diff --git a/docs/maui/behaviors/user-stopped-typing-behavior.md b/docs/maui/behaviors/user-stopped-typing-behavior.md index c13c9ac2..bafeed6b 100644 --- a/docs/maui/behaviors/user-stopped-typing-behavior.md +++ b/docs/maui/behaviors/user-stopped-typing-behavior.md @@ -2,13 +2,15 @@ title: UserStoppedTypingBehavior - .NET MAUI Community Toolkit author: cliffagius description: "The UserStoppedTypingBehavior is a Behavior that will trigger an action when a user has stopped data input on controls for example Entry, SearchBar and Editor. Examples of its usage include triggering a search when a user has stopped entering their search query." -ms.date: 04/13/2022 +ms.date: 10/23/2026 --- # UserStoppedTypingBehavior The `UserStoppedTypingBehavior` is a `Behavior` that will trigger an action when a user has stopped data input on controls for example `Entry`, `SearchBar` and `Editor`. Examples of its usage include triggering a search when a user has stopped entering their search query. +When `ShouldDismissKeyboardAutomatically` is `true`, the keyboard is dismissed once the user stopped typing, which also removes the focus from the input. The keyboard is only dismissed while the input has the focus: when the user moved to another view before the `StoppedTypingTimeThreshold` elapsed, the keyboard of that view stays open. + [!INCLUDE [important note on bindings within behaviors](../includes/behavior-bindings.md)] ## Syntax @@ -110,7 +112,7 @@ class UserStoppedTypingBehaviorPage : ContentPage |---------|---------|---------| | Command | [ICommand](xref:System.Windows.Input.ICommand) | The command to execute when the user has stopped providing input. | | MinimumLengthThreshold | int | The minimum length of the input value required before the command will be executed. | -| ShouldDismissKeyboardAutomatically | bool | Indicates whether or not the keyboard should be dismissed automatically. | +| ShouldDismissKeyboardAutomatically | bool | Indicates whether or not the keyboard should be dismissed automatically. Dismissing the keyboard also removes the focus from the input, and only happens while the input has the focus. | | StoppedTypingTimeThreshold | int | The time of inactivity in milliseconds after which the command will be executed. | ## Examples diff --git a/docs/maui/extensions/keyboard-extensions.md b/docs/maui/extensions/keyboard-extensions.md index 3b79ed2e..edd24ecb 100644 --- a/docs/maui/extensions/keyboard-extensions.md +++ b/docs/maui/extensions/keyboard-extensions.md @@ -2,7 +2,7 @@ title: KeyboardExtensions - .NET MAUI Community Toolkit author: PureWeen description: "The KeyboardExtensions provide a series of extension methods that support interacting with the Keyboard." -ms.date: 04/12/2023 +ms.date: 10/23/2026 --- # KeyboardExtensions @@ -21,7 +21,7 @@ The following methods allow you to close, show, and check if the keyboard is ope ### Hide Keyboard -The `HideKeyboardAsync` method will hide the Soft Input Keyboard if it is currently visible +The `HideKeyboardAsync` method will hide the Soft Input Keyboard if it is currently visible. It returns `true` if the platform was able to hide the keyboard. The following example shows how to hide the keyboard for a given entry: @@ -31,6 +31,8 @@ using CommunityToolkit.Maui.Core.Platform; entry.HideKeyboardAsync(CancellationToken.None); ``` +On Android, the keyboard is hidden through the window of the view that has the focus. That is the view itself while it has the focus, and otherwise the focused view of the activity's window. This makes `HideKeyboardAsync` work for an input inside a `Popup` or a modal page, which Android shows in a window of its own. + ### Show Keyboard The `ShowKeyboardAsync` method will show the Soft Input Keyboard and indicates what control you are opening it for From c41f6b176256e0acaeb8023eb3ddbfe119641d86 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:33:42 -0700 Subject: [PATCH 21/98] KeyboardExtensions: await the samples of HideKeyboardAsync and ShowKeyboardAsync Both methods return a ValueTask that the samples dropped. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/extensions/keyboard-extensions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maui/extensions/keyboard-extensions.md b/docs/maui/extensions/keyboard-extensions.md index edd24ecb..e0570b72 100644 --- a/docs/maui/extensions/keyboard-extensions.md +++ b/docs/maui/extensions/keyboard-extensions.md @@ -28,7 +28,7 @@ The following example shows how to hide the keyboard for a given entry: ```csharp using CommunityToolkit.Maui.Core.Platform; -entry.HideKeyboardAsync(CancellationToken.None); +await entry.HideKeyboardAsync(CancellationToken.None); ``` On Android, the keyboard is hidden through the window of the view that has the focus. That is the view itself while it has the focus, and otherwise the focused view of the activity's window. This makes `HideKeyboardAsync` work for an input inside a `Popup` or a modal page, which Android shows in a window of its own. @@ -41,7 +41,7 @@ The following example shows how to show the keyboard for a given entry: ```csharp using CommunityToolkit.Maui.Core.Platform; -entry.ShowKeyboardAsync(CancellationToken.None); +await entry.ShowKeyboardAsync(CancellationToken.None); ``` ### Is SoftKeyboard Showing From c5cbf82934c8dd9ec4c8dc9c4f58f48df06023d4 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:33:51 -0700 Subject: [PATCH 22/98] Map: document what each MapType shows on Windows Satellite shows aerial imagery without labels and Hybrid shows labels, as on iOS and Android. The Windows map used to show the labels for both, so the two looked the same; an app that chose Satellite to get labels has to choose Hybrid now. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/Map.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index 8e49ebff..0d6f083c 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -2,7 +2,7 @@ title: Map - .NET MAUI Community Toolkit author: jfversluis description: "The Map control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit." -ms.date: 06/13/2023 +ms.date: 10/23/2026 --- # Map @@ -23,6 +23,21 @@ The API of the .NET MAUI Community Toolkit implementation for Windows is not dif For details on how to work with this map control, please refer to the [.NET MAUI Map documentation](/dotnet/maui/user-interface/controls/map). +## Map types + +The `MapType` of the map decides what the Windows map shows, as it does on iOS and Android: + +|MapType |Windows shows | +|---------|---------| +| `Street` | The road map. | +| `Satellite` | Aerial imagery without place or road labels. | +| `Hybrid` | Aerial imagery with labels. | + +A value outside of the `MapType` enumeration shows the road map. + +> [!NOTE] +> Earlier versions showed the labels for `Satellite` too, so it looked the same as `Hybrid`. If your app chose `Satellite` on Windows to get labels, choose `Hybrid`. + ## Examples You can find examples of this control in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/tree/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/Maps). From 575f7580e13d82b63aea2024c6b77108c0ce6b7e Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:34:24 -0700 Subject: [PATCH 23/98] FileSaver: document that FilePath is a content:// URI on Android when the provider tells no path A written document whose file has no path that its documents provider tells (a document of a cloud provider, for example) used to make SaveAsync fail with "Unable to resolve absolute path". It is saved now, and FilePath is the content URI of the document, which the app opens with the ContentResolver. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/essentials/file-saver.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/maui/essentials/file-saver.md b/docs/maui/essentials/file-saver.md index 1730ee5f..275a50e0 100644 --- a/docs/maui/essentials/file-saver.md +++ b/docs/maui/essentials/file-saver.md @@ -2,7 +2,7 @@ title: FileSaver - .NET MAUI Community Toolkit author: VladislavAntonyuk description: The FileSaver provides the ability to select target folder and save files to the file system. -ms.date: 12/11/2022 +ms.date: 10/23/2026 --- # FileSaver @@ -137,6 +137,9 @@ async Task SaveFile(CancellationToken cancellationToken) } ``` +> [!NOTE] +> On Android, the user can save the file with a documents provider that doesn't tell the path of the file, for example a cloud provider. `FilePath` is then the `content://` URI of the document, and the save is successful. Open the document with the `ContentResolver` of Android instead of the `System.IO` classes. + ## Methods |Method |Description | @@ -151,7 +154,7 @@ The result returned from the `SaveAsync` method. This can be used to verify whet |Property |Type |Description | |---------|---------|---------| -| FilePath | `string` | The location on the disk where the file was saved. | +| FilePath | `string` | The location on the disk where the file was saved. On Android, a saved document whose file has no path that its documents provider tells, such as a document of a cloud provider, is reported by its `content://` URI. | | Exception | `Exception` | Gets the `Exception` if the save operation fails. | | IsSuccessful | `bool` | Gets a value determining whether the operation was successful. | From 8a26f27a24a0c10151aabcf370ae20b459b13506 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:34:38 -0700 Subject: [PATCH 24/98] FileSaver: document that the progress is a percentage, and fix the sample that set a ProgressBar with it The progress is reported as a percentage from 0 to 100 on every platform (it used to report a fraction from 0 to 1 and then 100). The sample assigned it to ProgressBar.Value, which .NET MAUI's ProgressBar does not have; its Progress property takes a fraction from 0 to 1. Also lists IsCancelled in the result. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/essentials/file-saver.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/maui/essentials/file-saver.md b/docs/maui/essentials/file-saver.md index 275a50e0..b1ef0828 100644 --- a/docs/maui/essentials/file-saver.md +++ b/docs/maui/essentials/file-saver.md @@ -118,13 +118,13 @@ async Task SaveFile(CancellationToken cancellationToken) } ``` -or in case the file is rather big and takes some time to be saved, you may be interested to know the progress: +or in case the file is rather big and takes some time to be saved, you may be interested to know the progress. The progress is reported as a percentage from 0 to 100. For a stream that can't seek, only the final 100 is reported: ```csharp async Task SaveFile(CancellationToken cancellationToken) { using var stream = new MemoryStream(Encoding.Default.GetBytes("Hello from the Community Toolkit!")); - var saverProgress = new Progress(percentage => ProgressBar.Value = percentage); + var saverProgress = new Progress(percentage => ProgressBar.Progress = percentage / 100); var fileSaverResult = await FileSaver.Default.SaveAsync("test.txt", stream, saverProgress, cancellationToken); if (fileSaverResult.IsSuccessful) { @@ -157,6 +157,7 @@ The result returned from the `SaveAsync` method. This can be used to verify whet | FilePath | `string` | The location on the disk where the file was saved. On Android, a saved document whose file has no path that its documents provider tells, such as a document of a cloud provider, is reported by its `content://` URI. | | Exception | `Exception` | Gets the `Exception` if the save operation fails. | | IsSuccessful | `bool` | Gets a value determining whether the operation was successful. | +| IsCancelled | `bool` | Gets a value determining whether the operation was cancelled. | #### Methods From 1fff6785146412384fae3e0f413f4330d85fa97f Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:35:11 -0700 Subject: [PATCH 25/98] Toast and Snackbar: document that overlapping Show and Dismiss calls take effect in call order on Windows On Windows, the Toast of the last Show is displayed and a final Dismiss leaves none; a Snackbar that a later call replaced or dismissed no longer stays on screen without its action, and Shown and Dismissed are raised in call order. The Task of a call completes after the earlier overlapping calls, and a call whose token is cancelled before its turn removes nothing. Warns that a Show or Dismiss that a Shown or Dismissed handler calls runs after the call that raised the event, so blocking on its Task inside the handler deadlocks. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/alerts/snackbar.md | 7 ++++++- docs/maui/alerts/toast.md | 4 +++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/maui/alerts/snackbar.md b/docs/maui/alerts/snackbar.md index 318d9ec9..bc9b309f 100644 --- a/docs/maui/alerts/snackbar.md +++ b/docs/maui/alerts/snackbar.md @@ -2,7 +2,7 @@ title: Snackbar - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Snackbar is a timed alert that appears at the bottom of the screen by default." -ms.date: 03/30/2022 +ms.date: 10/23/2026 --- # Snackbar @@ -122,6 +122,11 @@ The `SnackbarOptions` allows customize the default `Snackbar` style. > [!NOTE] > You can display only 1 `Snackbar` at the same time. If you call the `Show` method a second time, the first `Snackbar` will automatically be dismissed before the second `Snackbar` is shown. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called, and the `Shown` and `Dismissed` events are raised in that order. A `Snackbar` that a later call replaced or dismissed doesn't stay on screen. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Snackbar` throws an `OperationCanceledException` and removes nothing. + +> [!WARNING] +> On Windows, a `Show` or `Dismiss` that you call from a `Shown` or `Dismissed` handler runs after the `Show` or `Dismiss` call that raised the event has finished. Await it. Blocking on its `Task` inside the handler, for example with `.Wait()` or `.Result`, deadlocks. + ## Examples You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Alerts/SnackbarPage.xaml.cs). diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index b9788399..b5708119 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -2,7 +2,7 @@ title: Toast - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Toast is a timed alert that appears at the bottom of the screen by default." -ms.date: 03/30/2022 +ms.date: 10/23/2026 --- # Toast @@ -77,6 +77,8 @@ These values adhere to the constants defined in the [`android.widget.Toast` API] > [!NOTE] > You can display only one `Toast` at a time. If you call the `Show` method a second time, the first `Toast` will automatically be dismissed. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called: the `Toast` of the last `Show` is the one that is displayed, and a `Dismiss` after it leaves none. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Toast` throws an `OperationCanceledException` and removes nothing. + ## Examples You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Alerts/ToastPage.xaml.cs). From db320009520aa6d2da68b775693415a6c85f462b Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:35:44 -0700 Subject: [PATCH 26/98] CameraView: document two more start details (Windows cancelled start, Android start while connecting) On Windows, a StartCameraPreview that its own token cancels after the camera opened now stops the preview it showed and releases the camera; it used to throw and leave the preview running. On Android, a StartCameraPreview called while the view connects its camera waits for the connection, then starts the preview. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index a8091b4b..956397d0 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -664,6 +664,8 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) } ``` +On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. + A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, and an `InvalidOperationException` when the `CameraView` has no handler yet, for example before it is shown. ```cs @@ -776,7 +778,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` again. -A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when the page closes or the user taps a stop button while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. +A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when the page closes or the user taps a stop button while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. On Windows, a `StartCameraPreview` that its own token cancels after the camera has opened stops the preview that it had shown, and releases the camera. > [!IMPORTANT] > Catch the `OperationCanceledException` when you await these methods, in particular in an `async void` handler, where an exception that escapes ends the app. Call the start again if you still need the preview or the recording after a `StopCameraPreview` interrupted its start. From d80e46df8918e05d41e1c9c882280210cb33db13 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:38:01 -0700 Subject: [PATCH 27/98] Fix typos on the pages that this update touches A device's, status bar, "an Badge/Toast/Snackbar/FileSaver" in image alt text, SnackBar, "allows customize", dependant, programatically, "the header tapped", and a stray period after a link in the CameraView intro. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/alerts/snackbar.md | 8 ++++---- docs/maui/alerts/toast.md | 4 ++-- docs/maui/behaviors/statusbar-behavior.md | 8 ++++---- docs/maui/essentials/badge.md | 2 +- docs/maui/essentials/file-saver.md | 2 +- docs/maui/views/Expander.md | 2 +- docs/maui/views/MediaElement.md | 2 +- docs/maui/views/Popup.md | 2 +- docs/maui/views/camera-view.md | 2 +- 9 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/maui/alerts/snackbar.md b/docs/maui/alerts/snackbar.md index bc9b309f..25252e7e 100644 --- a/docs/maui/alerts/snackbar.md +++ b/docs/maui/alerts/snackbar.md @@ -56,11 +56,11 @@ When calling `Snackbar.Make()`, its parameter `string text` is required. All oth The following screenshot shows the resulting Snackbar: # [Android](#tab/snackbar-preview-android) -![Screenshot of an Snackbar on Android](../images/alerts/snackbar-android.gif "Snackbar on Android") +![Screenshot of a Snackbar on Android](../images/alerts/snackbar-android.gif "Snackbar on Android") # [iOS](#tab/snackbar-preview-ios) -![Screenshot of an Snackbar on iOS](../images/alerts/snackbar-ios.gif "Snackbar on iOS") +![Screenshot of a Snackbar on iOS](../images/alerts/snackbar-ios.gif "Snackbar on iOS") --- @@ -73,7 +73,7 @@ await MyVisualElement.DisplaySnackbar("Snackbar is awesome. It is anchored to My > [!WARNING] > `Snackbar` on Windows can't be anchored to `VisualElement` and is always displayed as a default Windows Notification. -`SnackBar` contains two events: +`Snackbar` contains two events: - `public static event EventHandler Shown` - `public static event EventHandler Dismissed` @@ -98,7 +98,7 @@ Snackbar.Dismissed += (s, e) => { Console.WriteLine(Snackbar.IsShown); }; ### SnackbarOptions -The `SnackbarOptions` allows customize the default `Snackbar` style. +The `SnackbarOptions` allows you to customize the default `Snackbar` style. #### Properties diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index b5708119..c8423f7e 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -42,11 +42,11 @@ When calling `Toast.Make()`, its parameter `string text` is required. All other The following screenshot shows the resulting Toast: ### [Android](#tab/toast-preview-android) -![Screenshot of an Toast on Android](../images/alerts/toast-android.gif "Toast on Android") +![Screenshot of a Toast on Android](../images/alerts/toast-android.gif "Toast on Android") ### [iOS](#tab/toast-preview-ios) -![Screenshot of an Toast on iOS](../images/alerts/toast-ios.gif "Toast on iOS") +![Screenshot of a Toast on iOS](../images/alerts/toast-ios.gif "Toast on iOS") --- diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index 612c9261..ffe40893 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -1,13 +1,13 @@ --- title: StatusBarBehavior - .NET MAUI Community Toolkit author: pictos -description: "The StatusBarBehavior provides the ability to customize the color and style of a devices status bar." +description: "The StatusBarBehavior provides the ability to customize the color and style of a device's status bar." ms.date: 10/23/2026 --- # StatusBarBehavior -The `StatusBarBehavior` provides the ability to customize the color and style of a devices status bar. +The `StatusBarBehavior` provides the ability to customize the color and style of a device's status bar. The `StatusBarBehavior` applies the color and style values when the properties are updated. The values are also applied based on the `ApplyOn` property, this property makes it possible to define which lifecycle event is used: @@ -65,7 +65,7 @@ class MyPage : ContentPage } ``` -There's another way to access the Statusbar APIs on C#, you can call the methods directly, as you can see in the snippet below: +There's another way to access the status bar APIs in C#, you can call the methods directly, as you can see in the snippet below: ```csharp class MyPage : ContentPage @@ -80,7 +80,7 @@ class MyPage : ContentPage ``` > [!WARNING] -> If you want to add this code the `MainPage`'s constructor, `OnAppearing` or `OnNavigatedTo` methods, please use the `Behavior` instead. +> If you want to add this code to the `MainPage`'s constructor, `OnAppearing` or `OnNavigatedTo` methods, please use the `Behavior` instead. > Using directly on these places can crash your application since the platform-specific components may not be initialized. ## Configuration diff --git a/docs/maui/essentials/badge.md b/docs/maui/essentials/badge.md index 17963138..84d5c405 100644 --- a/docs/maui/essentials/badge.md +++ b/docs/maui/essentials/badge.md @@ -9,7 +9,7 @@ ms.date: 10/23/2026 The `Badge` API allows developers to set the app icon badge number on the home screen. -![Screenshot of an Badge on Windows](../images/essentials/badge-windows.gif "Badge on Windows") +![Screenshot of a Badge on Windows](../images/essentials/badge-windows.gif "Badge on Windows") --- diff --git a/docs/maui/essentials/file-saver.md b/docs/maui/essentials/file-saver.md index b1ef0828..5180741f 100644 --- a/docs/maui/essentials/file-saver.md +++ b/docs/maui/essentials/file-saver.md @@ -9,7 +9,7 @@ ms.date: 10/23/2026 The `FileSaver` provides the ability to select a target folder and save files to the file system. -![Screenshot of an FileSaver on macOS](../images/essentials/file-saver-mac.png "FileSaver on macOS") +![Screenshot of a FileSaver on macOS](../images/essentials/file-saver-mac.png "FileSaver on macOS") The following preconditions are required for the `FileSaver`: # [Android](#tab/android) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index 45eeddc5..bb340e41 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -21,7 +21,7 @@ This `Header` property can be provided with any view to allow for full customiza This is the main content that will show when the `Header` property is interacted with it (clicked or tapped) or the `IsExpanded` property is modified. > [!NOTE] -> `Expander` may work unexpectedly if it is placed inside `ListView` or `CollectionView`. However, it can be controlled with the custom implementation by setting `public Action? HandleHeaderTapped { get; set; }`. This action is executed each time the header tapped. Please pay attention, by changing this action you may receive different behavior in `CollectionView` and `ListView` on all platforms. +> `Expander` may work unexpectedly if it is placed inside `ListView` or `CollectionView`. However, it can be controlled with the custom implementation by setting `public Action? HandleHeaderTapped { get; set; }`. This action is executed each time the header is tapped. Please pay attention, by changing this action you may receive different behavior in `CollectionView` and `ListView` on all platforms. > [!NOTE] > The `Expander` lays out its `Header` and `Content` in a `Grid` of its own. An implicit `Style` for `Grid`, for example one in _App.xaml_, doesn't apply to that `Grid` unless the `Style` sets `ApplyToDerivedTypes`. Even then the `Background` and `BackgroundColor` of that `Grid` stay `null`, so the background of the `Expander` shows behind the `Header` and the `Content`. diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index d89e3f93..72825ce0 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -122,7 +122,7 @@ No setup is required. ## Supported Formats -The supported multimedia formats can be different per platform. In some cases it can even be dependant on what decoders are available or installed on the operating system that is used while running your app. For more detailed information on which formats are supported on each platform, please refer to the links below. +The supported multimedia formats can be different per platform. In some cases it can even be dependent on what decoders are available or installed on the operating system that is used while running your app. For more detailed information on which formats are supported on each platform, please refer to the links below. |Platform| Link | Notes | |--------|------|-------| diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index 769383af..f879e444 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -131,7 +131,7 @@ There are 2 different ways that a `Popup` can be closed: ### 1. Programmatically closing a Popup -There are 3 options to close a `Popup` programatically: +There are 3 options to close a `Popup` programmatically: 1. In a `ContentPage`, use the `this.ClosePopupAsync()` extension method 2. In an app using `Shell`, use `Shell.Current.ClosePopupAsync()` extension method diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 956397d0..c499628e 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -9,7 +9,7 @@ ms.date: 10/23/2026 The `CameraView` provides the ability to connect to a camera, display a preview from the camera, take photos, and record videos. The `CameraView` also offers features to support controlling the flash and torch, adjusting zoom, saving captured media to a file, and offering different hooks for events. -The following sections will incrementally build on how to use the `CameraView` in a .NET MAUI application. They rely on the use of a [`CameraViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/CameraView/CameraViewViewModel.cs). that will be set as the `BindingContext` of the example [`CameraViewPage`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/CameraView/CameraViewPage.xaml). +The following sections will incrementally build on how to use the `CameraView` in a .NET MAUI application. They rely on the use of a [`CameraViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/CameraView/CameraViewViewModel.cs) that will be set as the `BindingContext` of the example [`CameraViewPage`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/CameraView/CameraViewPage.xaml). ## Platform specific initialization From 9f779f53840cc36752917e78e0522048961cd5b7 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:38:16 -0700 Subject: [PATCH 28/98] CameraView: document what changing SelectedCamera does Changing it while the preview runs restarts the preview with the new camera, a camera that cannot be started is reported through ErrorOccurred, and on Android the change waits until a running video recording is stopped or replaced. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/camera-view.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index c499628e..3f72b266 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -218,6 +218,8 @@ The result will be a surface rendering the output of the default camera connecte The `SelectedCamera` property provides the ability to access the currently selected camera. +Changing `SelectedCamera` while the preview runs restarts the preview with the new camera. If the new camera can't be started, for example because another app is using it, the failure is reported through the `ErrorOccurred` event, and selecting another camera starts the preview with that camera. On Android, selecting another camera while a video recording runs doesn't end the recording: the change is applied when the recording is stopped or replaced. `StopCameraPreview` cancels a camera switch that is still waiting for the platform, see [Cancel pending starts](#cancel-pending-starts). + The following example shows how to bind the `SelectedCamera` property from the `CameraView` to a property on the `CameraViewModel` with the same name (`SelectedCamera`). ```xaml From b9dc8b91b1a85b90237e79caccd8e7d5f710751e Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:38:38 -0700 Subject: [PATCH 29/98] Popup: document that an oversized WidthRequest or HeightRequest is limited to the window While a Popup is displayed, a WidthRequest or HeightRequest larger than the space inside the window (minus the Margin and the stroke of the Shape) is limited to that space, so the Popup keeps its Margin and the user can tap outside of it. The values of the properties do not change. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/Popup.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index f879e444..9899439e 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -96,6 +96,8 @@ The default values for `HorizontalOptions` and `VerticalOptions` will result in A popup will present with a default `Padding` of 15. In order to make the `SimplePopup` look better a `Padding` of 10 has been added. +A `WidthRequest` or `HeightRequest` that is larger than the space inside the window, minus the `Margin` and the stroke of the `Shape`, is limited to that space while the `Popup` is displayed. The `Popup` then keeps its `Margin` to the edges of the window, so the user can still tap outside of it. The values of `WidthRequest` and `HeightRequest` don't change. + > [!TIP] > For more advanced scenarios, such as returning a result from a `Popup`, the code-behind file (_*.xaml.cs_) must inherit from `Popup` or `Popup` (found in `CommunityToolkit.Maui.Views`). For a complete example demonstrating this, please refer to [Popup - Returning a result](./popup/popup-result.md). From 3480ba733ff1cecc862f9db9daaf47283c944184 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:38:46 -0700 Subject: [PATCH 30/98] Popup: document that Opened is raised once each time the Popup is shown PopupPage notifies the Popup only the first time it is navigated to, so closing a page or another Popup that was displayed above it does not raise Opened again. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/views/Popup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index 9899439e..e10c7776 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -332,7 +332,7 @@ The `Popup` class provides the following events that can be subscribed to. |Event | Description | |---------|---------| | `Closed` | Occurs when the `Popup` is closed. | -| `Opened` | Occurs when the `Popup` is opened. | +| `Opened` | Occurs when the `Popup` is opened. It is raised once each time the `Popup` is shown, and not again when a page or another `Popup` that was displayed above it is closed. | ## Examples From 49762f1d74e48c86d2c06b113748c92fe5338a08 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:39:05 -0700 Subject: [PATCH 31/98] DialogFragmentService: add an FAQ entry for modal page content behind the status bar Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/platform-specific/DialogFragment-customization.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index bbeeb553..dfbef1d8 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -130,6 +130,12 @@ public static class MauiProgram And now, all modals will be showed in full-screen mode. +## Frequently asked questions + +### Why is the content of my modal page behind the status bar on Android? + +When the `DialogFragmentService` is enabled, it lays out the dialog of a modal page like the window of the activity: the content of the page extends behind the status bar, whatever the status bar color is. Keep the content clear of the status bar with the safe area, for example by setting the `SafeAreaEdges` of the page to `SafeAreaRegions.Container`. See [Modal page layout](#modal-page-layout). + ## API You can find the source code for `IDialogFragmentService` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui.Core/Interfaces/IDialogFragmentService.android.cs) and about the `FragmentLifecycleManager` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui.Core/Services/FragmentLifecycleManager.android.cs). From 2b1e075dbec0a4ba61f09cffb24538ba7f2144da Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:42:16 -0700 Subject: [PATCH 32/98] Options: end the samples with a semicolon `builder.UseMauiCommunityToolkit(options => { ... })` is a statement and does not compile without it. Co-Authored-By: Claude Sonnet 5.5 --- docs/maui/options.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/maui/options.md b/docs/maui/options.md index c73c0d03..b4f2ac1e 100644 --- a/docs/maui/options.md +++ b/docs/maui/options.md @@ -18,7 +18,7 @@ builder.UseMauiCommunityToolkit(options => options.SetShouldSuppressExceptionsInConverters(false); options.SetShouldSuppressExceptionsInBehaviors(false); options.SetShouldSuppressExceptionsInAnimations(false); -}) +}); ``` ## SetShouldSuppressExceptionsInConverters @@ -35,7 +35,7 @@ var builder = MauiApp.CreateBuilder(); builder.UseMauiCommunityToolkit(options => { options.SetShouldSuppressExceptionsInConverters(true); -}) +}); ``` ### Default Return Values @@ -87,7 +87,7 @@ var builder = MauiApp.CreateBuilder(); builder.UseMauiCommunityToolkit(options => { options.SetShouldSuppressExceptionsInAnimations(true); -}) +}); ``` ## SetShouldSuppressExceptionsInBehaviors @@ -104,7 +104,7 @@ var builder = MauiApp.CreateBuilder(); builder.UseMauiCommunityToolkit(options => { options.SetShouldSuppressExceptionsInBehaviors(true); -}) +}); ``` ## SetPopupDefaults @@ -122,7 +122,7 @@ builder.UseMauiCommunityToolkit(options => Margin = 72, BackgroundColor = Colors.Orange }); -}) +}); ``` ## SetPopupOptionsDefaults @@ -139,7 +139,7 @@ builder.UseMauiCommunityToolkit(options => { PageOverlayColor = Colors.Orange }); -}) +}); ``` ## SetShouldUseStatusBarBehaviorOnAndroidModalPage @@ -155,5 +155,5 @@ var builder = MauiApp.CreateBuilder(); builder.UseMauiCommunityToolkit(options => { options.SetShouldUseStatusBarBehaviorOnAndroidModalPage(true); -}) +}); ``` From 41144b98e84ac91983993b7d58657b839c410ad5 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:01:38 -0700 Subject: [PATCH 33/98] CameraView: an awaited start throws OperationCanceledException when the app calls StopCameraPreview, not when the page closes Closing the page does not cancel a pending start: the handler's disconnection and disposal neither call StopCameraPreview nor cancel its token (on Windows a start whose MediaCapture was released ends quietly), so the example names the app's own StopCameraPreview in OnDisappearing or a stop button. The note under Request permissions no longer says that a start before the permission is granted always fails: it says that a start that fails for lack of the permission is reported and leaves the preview stopped, as the code and the XML docs of StartCameraPreview do. StartCameraPreview also throws InvalidOperationException after the handler was disconnected, as its XML docs say. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 3f72b266..747d9a70 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -190,7 +190,7 @@ var microphonePermissionsRequest = await Permissions.RequestAsync [!NOTE] -> A `CameraView` can try to start its preview before the camera permission is granted, for example while your app is still asking for it. The failure is reported through the [`ErrorOccurred`](#events) event. On Android, the preview then starts by itself when the app resumes with the permission granted. On the other platforms, call `StartCameraPreview` again once the permission is granted. See [Start preview](#start-preview) for details. +> A `CameraView` connects to its camera and starts its preview when it is shown, which can be before your app has the camera permission, for example while your app is still asking for it. A start that fails because the app doesn't have the permission is reported through the [`ErrorOccurred`](#events) event, and the preview stays stopped. On Android, the preview then starts by itself when the app resumes with the permission granted. On the other platforms, call `StartCameraPreview` again once the app has the permission. See [Start preview](#start-preview) for details. ### Including the XAML namespace @@ -668,7 +668,7 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, and an `InvalidOperationException` when the `CameraView` has no handler yet, for example before it is shown. +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, and an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected. ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); @@ -780,7 +780,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` again. -A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when the page closes or the user taps a stop button while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. On Windows, a `StartCameraPreview` that its own token cancels after the camera has opened stops the preview that it had shown, and releases the camera. +A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when your app calls `StopCameraPreview` in `OnDisappearing`, or from a stop button, while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. On Windows, a `StartCameraPreview` that its own token cancels after the camera has opened stops the preview that it had shown, and releases the camera. > [!IMPORTANT] > Catch the `OperationCanceledException` when you await these methods, in particular in an `async void` handler, where an exception that escapes ends the app. Call the start again if you still need the preview or the recording after a `StopCameraPreview` interrupted its start. From 46fa6a177d30f5b18e58b3094ca854919e882a0c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:02:09 -0700 Subject: [PATCH 34/98] CameraView: the video recording samples catch the OperationCanceledException of a start that StopCameraPreview cancels Both samples are async void handlers that await StartVideoRecording without a catch. StopCameraPreview now cancels a recording that has not started, and the exception would escape the handler and end the app, which the IMPORTANT note under Cancel pending starts tells readers to prevent. They now catch it, and any other exception, like the CaptureImage and StartCameraPreview samples on the same page. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 48 +++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 747d9a70..36abc55c 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -549,13 +549,25 @@ The following example demonstrates how to use the `StartVideoRecording` method: ```cs async void StartCameraRecordingWithCustomStream(object? sender, EventArgs e) { - using var threeSecondVideoRecordingStream = new FileStream("recording.mp4", FileMode.Create); - await Camera.StartVideoRecording(threeSecondVideoRecordingStream, CancellationToken.None); + try + { + using var threeSecondVideoRecordingStream = new FileStream("recording.mp4", FileMode.Create); + await Camera.StartVideoRecording(threeSecondVideoRecordingStream, CancellationToken.None); - await Task.Delay(TimeSpan.FromSeconds(3)); - - await Camera.StopVideoRecording(CancellationToken.None); - await FileSaver.SaveAsync("recording.mp4", threeSecondVideoRecordingStream); + await Task.Delay(TimeSpan.FromSeconds(3)); + + await Camera.StopVideoRecording(CancellationToken.None); + await FileSaver.SaveAsync("recording.mp4", threeSecondVideoRecordingStream); + } + catch(OperationCanceledException) + { + // StopCameraPreview was called before the recording started + } + catch(Exception ex) + { + // Handle Exception + Trace.WriteLine(ex); + } } ``` @@ -564,12 +576,24 @@ In case you want to record a short video and record video in `MemoryStream` you ```cs async void StartCameraRecording(object? sender, EventArgs e) { - await Camera.StartVideoRecording(CancellationToken.None); - - await Task.Delay(TimeSpan.FromSeconds(3)); - - var threeSecondVideoRecordingStream = await Camera.StopVideoRecording(CancellationToken.None); - await FileSaver.SaveAsync("recording.mp4", threeSecondVideoRecordingStream); + try + { + await Camera.StartVideoRecording(CancellationToken.None); + + await Task.Delay(TimeSpan.FromSeconds(3)); + + var threeSecondVideoRecordingStream = await Camera.StopVideoRecording(CancellationToken.None); + await FileSaver.SaveAsync("recording.mp4", threeSecondVideoRecordingStream); + } + catch(OperationCanceledException) + { + // StopCameraPreview was called before the recording started + } + catch(Exception ex) + { + // Handle Exception + Trace.WriteLine(ex); + } } ``` From cb0e69e37ed924dc71818085535df2e4cfa4398f Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:02:47 -0700 Subject: [PATCH 35/98] MediaElement: state the Windows Speed fix as what Speed does, not as a change "No longer undoes" reads as release notes in a property table. The row now says what holds: a playback rate that the player reports after a newer Speed was set doesn't change Speed back (MediaManager.windows.cs applies the queued rate only while the open session still has it). Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/MediaElement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 72825ce0..0c4bb4c3 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -462,7 +462,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide | ShouldMute | `bool` | Determines whether the audio is currently muted. This is a bindable property. | `false` | | ShouldShowPlaybackControls | `bool` | Determines whether the platforms playback controls are displayed. This is a bindable property. Note that on iOS and Windows the controls are only shown for a brief period after interacting with the screen. There is no way of keeping the controls visible at all times. | `true` | | Source | `MediaSource?` | The source of the media loaded into the control. | `null` | -| Speed | `double` | Determines the playback speed of the media. This is a bindable property. On Windows, a late notification of an earlier playback rate no longer undoes a `Speed` that was set after it. | `1` | +| Speed | `double` | Determines the playback speed of the media. This is a bindable property. On Windows, a playback rate that the player reports after a newer `Speed` was set doesn't change `Speed` back. | `1` | | MediaHeight | `int` | The height of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | | MediaWidth | `int` | The width of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | | Volume | `double` | Determines the media's volume, which is represented on a linear scale between 0 and 1. This is a bindable property. | `1` | From 07954cb544b74451e5f6cb2bf6fcc9393ea2c665 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:03:26 -0700 Subject: [PATCH 36/98] StatusBarBehavior: modal page content extends behind the status bar; the iOS style belongs to the app and is set on the main thread The Android tab said that the Dialog Fragment Service page describes how a modal page is laid out below the status bar. With the service, the content of a modal page extends behind the status bar and keeps clear of it with the safe area, which is what that page describes. From the remarks of StatusBar.SetStyle (.NET 10, the target framework that the toolkit ships): the style belongs to the whole app, so the status bar of every window shows it, and a call from a thread other than the main thread throws UIKitThreadAccessException, also in a Release build. StatusBarBehavior calls SetStyle when its StatusBarStyle changes, so the same holds for the behavior. Co-Authored-By: Claude Opus 5.5 --- docs/maui/behaviors/statusbar-behavior.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index ffe40893..79076eb8 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -83,13 +83,16 @@ class MyPage : ContentPage > If you want to add this code to the `MainPage`'s constructor, `OnAppearing` or `OnNavigatedTo` methods, please use the `Behavior` instead. > Using directly on these places can crash your application since the platform-specific components may not be initialized. +> [!NOTE] +> On iOS, call `StatusBar.SetStyle`, and change the `StatusBarStyle` of a `StatusBarBehavior`, on the main thread. A call from another thread throws a `UIKitThreadAccessException`. + ## Configuration # [Android](#tab/android) No changes needed. -To apply the status bar color and style of the activity to modal pages as well, see [Dialog Fragment Service](../platform-specific/DialogFragment-customization.md). That page also describes how a modal page is laid out below the status bar. +To apply the status bar color and style of the activity to modal pages as well, see [Dialog Fragment Service](../platform-specific/DialogFragment-customization.md). That page also describes how the content of a modal page extends behind the status bar, and how to keep it clear of the status bar. # [iOS](#tab/ios) @@ -105,7 +108,7 @@ If your _Platforms/iOS/Info.plist_ file contains the following entry, which earl > [!IMPORTANT] > In an app that is built with the iOS 27 SDK (Xcode 27) or later, UIKit ignores `UIApplication.SetStatusBarStyle`. With the key set to `false` the style of the status bar then doesn't change, and the toolkit writes the message _Unable to apply the Status Bar Style because Info.plist sets UIViewControllerBasedStatusBarAppearance to false: remove the key from Info.plist_ to the trace output. An app that is built with an earlier SDK still applies the style while the key is `false`, but the key isn't needed there either. -On .NET 10, the first `LightContent` or `DarkContent` that you set makes the view controllers that don't choose a style of their own return the one you set. `Default` gives every view controller its own style back. A view controller that overrides `preferredStatusBarStyle` keeps its own style, and so does `SFSafariViewController`. +On .NET 10, the style belongs to the whole app: the status bar of every window shows it. The first `LightContent` or `DarkContent` that you set makes the view controllers that don't choose a style of their own return the one you set. `Default` gives every view controller its own style back. A view controller that overrides `preferredStatusBarStyle` keeps its own style, and so does `SFSafariViewController`. ----- From 626a117d7865b47afd6585f9cbe0a3c1b1d86ebe Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:03:43 -0700 Subject: [PATCH 37/98] PopupOptions: link to Popup.md with the case of its file name The page is docs/maui/views/Popup.md. The new link to its Setting Popup Defaults section, and the two older links next to it, pointed to popup.md, which a case-sensitive file system does not find. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/popup/popup-options.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/popup/popup-options.md b/docs/maui/views/popup/popup-options.md index e392e26b..d98d1df7 100644 --- a/docs/maui/views/popup/popup-options.md +++ b/docs/maui/views/popup/popup-options.md @@ -9,9 +9,9 @@ ms.date: 10/23/2026 The `PopupOptions` class provides the ability to customize the appearance and behavior of the `Popup`. -All of the examples in this page make use of the `SimplePopup` example that is covered at [`Popup`](../popup.md). +All of the examples in this page make use of the `SimplePopup` example that is covered at [`Popup`](../Popup.md). -The options that you don't set start with the values of `DefaultPopupOptionsSettings`, which you can change with `SetPopupOptionsDefaults`. A `Popup` that is shown without `PopupOptions` uses these values too. See [Setting Popup Defaults](../popup.md#setting-popup-defaults) for how they combine with the other settings of a `Popup`. +The options that you don't set start with the values of `DefaultPopupOptionsSettings`, which you can change with `SetPopupOptionsDefaults`. A `Popup` that is shown without `PopupOptions` uses these values too. See [Setting Popup Defaults](../Popup.md#setting-popup-defaults) for how they combine with the other settings of a `Popup`. ## Controlling whether the user can dismiss the Popup @@ -139,7 +139,7 @@ You can find the source code for `PopupOptions` over on the [.NET MAUI Community ## Additional Resources -- [`Popup`](../popup.md) +- [`Popup`](../Popup.md) - [`IPopupService`](../popup-service.md) - [`Popup` - Returning a result](./popup-result.md) - [`Popup` - Combining Popup features to provide a comprehensive example](./popup-complex.md) From 27e737d154975ec670416d61a9aca2ea25d6f722 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:03:58 -0700 Subject: [PATCH 38/98] Popup: name both default background colors in the precedence exceptions "The color fills the background" left open which color. PopupPage fills the background of a Popup that has neither a BackgroundColor nor a Background with DefaultPopupSettings.BackgroundColor, or with BackgroundColorDark while the app uses the dark theme (BackgroundColorConverter over an AppThemeColor), and neither is the default value of Popup.BackgroundColor. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Popup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index e10c7776..f31561cd 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -275,7 +275,7 @@ The settings above are defaults, and a value that you set on a `Popup` or a `Pop A few cases don't follow that order: - **Margin, HorizontalOptions and VerticalOptions.** A `Popup` whose `Margin` is 0 on every side, or whose `HorizontalOptions` or `VerticalOptions` is `LayoutOptions.Fill`, is displayed with the value of `DefaultPopupSettings` instead. The properties of the `Popup` keep their value. -- **Background.** `DefaultPopupSettings.BackgroundColor` isn't the default value of `BackgroundColor`. The `BackgroundColor` of a `Popup` is `null` until a value, a binding or a `Style` sets it. The color fills the background of a `Popup` that has neither a `BackgroundColor` nor a `Background`. When the `Popup` has a `Background`, that brush is drawn instead. +- **Background.** `DefaultPopupSettings.BackgroundColor` and `DefaultPopupSettings.BackgroundColorDark` aren't default values of `BackgroundColor`: the `BackgroundColor` of a `Popup` is `null` until a value, a binding or a `Style` sets it. While a `Popup` has neither a `BackgroundColor` nor a `Background`, `DefaultPopupSettings.BackgroundColor` fills its background, or `DefaultPopupSettings.BackgroundColorDark` while the app uses the dark theme. When the `Popup` has a `Background`, that brush is drawn instead. - **A view that isn't a Popup.** When you show a view that isn't a `Popup`, the `Popup` that the toolkit creates for it binds its `Margin`, `HorizontalOptions`, `VerticalOptions`, `Background`, `BackgroundColor` and, when the view has a `Padding`, its `Padding` to those of the view, so a `Style` can't set them. A margin or padding of the view that is 0 on every side gives the `Popup` the `Margin` or `Padding` of `DefaultPopupSettings`. - **Dismissing the popup.** A tap outside of the `Popup`, or the hardware back button on Android, dismisses the `Popup` only while both `Popup.CanBeDismissedByTappingOutsideOfPopup` and `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` are `true`. While either is `false`, both do nothing. From 7d24d2e6e07e902a7c73e3244bb413dd1f29e1a8 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:04:18 -0700 Subject: [PATCH 39/98] Expander: ExpandedChanged and Command follow IsExpanded; TalkBack's double tap taps the header OnIsExpandedPropertyChanged runs Command and raises ExpandedChanged for every change of IsExpanded, also one made by code, as it does on main: the page said that both happen when the header is tapped (and, after the accessibility update, activated). The Android row said that "the click of a TapGestureRecognizer on the Header stays available". The click that MAUI offers TalkBack is the one of the Expander's own recognizer on the header, so a TalkBack double tap still toggles the Expander; the row now says that. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Expander.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index bb340e41..ac3f2b29 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -134,7 +134,7 @@ Keyboard and screen reader users can expand and collapse an `Expander` through i |Platform |Behavior | |---------|---------| | Windows | The `Expander` is a Tab stop. Enter toggles it when it is pressed and Space when it is released, like a `Button`. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | -| Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand or collapse action in its actions menu. The click of a `TapGestureRecognizer` on the `Header` stays available. | +| Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand or collapse action in its actions menu. A double tap with TalkBack still taps the `Header`, which toggles the `Expander`. | | iOS and Mac Catalyst | VoiceOver reads the whole `Header` as one button that a double tap toggles. The element has the button trait, and the header trait when the `Header` is a heading. Its label, hint and `AutomationId` come from the `Header`. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A `Header` that holds a control, such as a `Button`, a `Switch` or an `Entry`, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the `Expander` for it. A `Header` with another `TapGestureRecognizer` lets VoiceOver tap it, so that every recognizer runs. | Every activation from the keyboard or from assistive technology goes through the same code as a tap, so `IsExpanded`, `Command` and `CommandParameter`, `ExpandedChanged` and `HandleHeaderTapped` behave as for a tap. In a `CollectionView` on Windows, such an activation still resizes the item that holds the `Expander`. @@ -155,7 +155,7 @@ The accessibility support changes what UI automation finds: |Property |Type |Description | |---------|---------|---------| -`Command` | `ICommand` | Executes when the `Expander` header is tapped. +`Command` | `ICommand` | Executes when `IsExpanded` changes, for example when the `Expander` header is tapped. `CommandParameter` | `object` | The parameter that's passed to `Command`. `Direction` | `ExpandDirection` | Defines the expander direction. `Content` | `IView?` | Defines the content to be displayed when the `Expander` expands. @@ -169,7 +169,7 @@ The `ExpandDirection` enumeration defines the following members: | `Down` | Indicates that the `Expander` content is under the header. | | `Up` | Indicates that the `Expander` content is above the header. | -The `Expander` control also defines a `ExpandedChanged` event that's fired when the `Expander` header is tapped, or activated from the keyboard or by assistive technology. +The `Expander` control also defines an `ExpandedChanged` event that's fired when `IsExpanded` changes: when the `Expander` header is tapped, or activated from the keyboard or by assistive technology, and when code changes `IsExpanded`. ### ExpandedChangedEventArgs From f38eb1aec2ccb7fcda55fdb8b63c04b40d1a5364 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:04:35 -0700 Subject: [PATCH 40/98] SemanticOrderView: the intro no longer says that ViewOrder orders screen readers on Windows The first sentence read as if ViewOrder set the screen reader order on every platform and, in addition, the Tab order on Windows. On Windows it sets only the Tab order (Narrator follows the visual tree, as the XML docs of ViewOrder say), so the sentence now names the platforms of each. The Windows row adds that only views that can take the keyboard focus are Tab stops: the page's own example orders two Labels, whose TextBlocks WinUI never focuses, so it changes nothing on Windows. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/semantic-order-view.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index cb673616..f0e9f593 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -7,7 +7,7 @@ ms.date: 10/23/2026 # SemanticOrderView -The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers, and on Windows the keyboard Tab order, and improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. +The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers on Android, iOS and Mac Catalyst, and the keyboard Tab order on Windows, to improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. ## Using the SemanticOrderView @@ -62,7 +62,7 @@ The views that aren't in `ViewOrder` stay accessible on every platform. |---------|---------| | iOS and Mac Catalyst | The views of `ViewOrder` are the first accessibility elements of the `SemanticOrderView`, in that order. Assistive technologies visit the other views after them, in the order of the view hierarchy. | | Android | On Android 5.1 (API 22) or later, the order of `ViewOrder` determines how TalkBack traverses the views. On earlier versions the order isn't applied, and a message is written to the trace output. | -| Windows | `ViewOrder` sets the keyboard Tab order of the views. It doesn't change the order in which Narrator reads them, which follows the visual tree. | +| Windows | `ViewOrder` sets the keyboard Tab order of the views. It doesn't change the order in which Narrator reads them, which follows the visual tree. Only views that can take the keyboard focus, such as a `Button` or an `Entry`, are Tab stops, so ordering `Label` views, as in the example above, has no effect on Windows. | On Windows, the views of `ViewOrder` that the `SemanticOrderView` holds come first among the Tab stops of the `SemanticOrderView`, in the order of `ViewOrder`, followed by the rest of its content in the order of the visual tree. The Tab key reaches the controls above the `SemanticOrderView` before these views, and the controls below it after them. A view of `ViewOrder` that is inside a control within the `SemanticOrderView`, such as a `ScrollView`, or outside of the `SemanticOrderView`, gets a `TabIndex` instead. That `TabIndex` orders it among the Tab stops of the nearest control that holds it. From 7fdd56f85582d561a48cf4a0b440bc1f1b6d3156 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:05:41 -0700 Subject: [PATCH 41/98] FileSaver: tell apps that used the progress as a fraction to divide it by 100 On main, SaveAsync reported totalRead / stream.Length (0 to 1) while it copied the stream and 100 at the end, on Android and in the shared copy that the other platforms use. It now reports percentages throughout, so an app that set ProgressBar.Progress to the reported value fills the bar at once. Co-Authored-By: Claude Opus 5.5 --- docs/maui/essentials/file-saver.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/maui/essentials/file-saver.md b/docs/maui/essentials/file-saver.md index 5180741f..53807f21 100644 --- a/docs/maui/essentials/file-saver.md +++ b/docs/maui/essentials/file-saver.md @@ -137,6 +137,9 @@ async Task SaveFile(CancellationToken cancellationToken) } ``` +> [!NOTE] +> Earlier versions reported the progress as a fraction from 0 to 1 while the file was saved, and then 100. If your app uses the progress as a fraction, divide it by 100, as the example above does. + > [!NOTE] > On Android, the user can save the file with a documents provider that doesn't tell the path of the file, for example a cloud provider. `FilePath` is then the `content://` URI of the document, and the save is successful. Open the document with the `ContentResolver` of Android instead of the `System.IO` classes. From 84aa6fc248b59d4235c62858d7d14fc9bd8c3695 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:06:03 -0700 Subject: [PATCH 42/98] DialogFragmentService: the custom service samples compile and use a type pattern instead of { } The registration sample missed the semicolon after MauiApp.CreateBuilder(). The service sample matched the dialog's window with the empty property pattern { }, which the toolkit's code style does not use; it now tests Dialog?.Window against Android.Views.Window, named in full because Microsoft.Maui.Controls.Window is in scope in a .NET MAUI project. Co-Authored-By: Claude Opus 5.5 --- docs/maui/platform-specific/DialogFragment-customization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index dfbef1d8..9c2fe5b7 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -69,7 +69,7 @@ sealed class MyDialogFragmentService : IDialogFragmentService return; } - if (dialogFragment is not { Dialog.Window: { } window }) + if (dialogFragment.Dialog?.Window is not Android.Views.Window window) { return; } @@ -102,7 +102,7 @@ public static class MauiProgram public static MauiApp CreateMauiApp() { - var builder = MauiApp.CreateBuilder() + var builder = MauiApp.CreateBuilder(); builder.ConfigureLifecycleEvents(static lifecycleBuilder => { lifecycleBuilder.AddAndroid(static androidBuilder => From 833424a73b03649e9f0ee626a34780f34afee6a5 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:06:14 -0700 Subject: [PATCH 43/98] KeyboardExtensions: the IsSoftKeyboardShowing sample is a statement that compiles Like the HideKeyboardAsync and ShowKeyboardAsync samples above it, which now await their ValueTask, the sample ends with a semicolon and keeps the bool that the method returns. Co-Authored-By: Claude Opus 5.5 --- docs/maui/extensions/keyboard-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/extensions/keyboard-extensions.md b/docs/maui/extensions/keyboard-extensions.md index e0570b72..e574bfe4 100644 --- a/docs/maui/extensions/keyboard-extensions.md +++ b/docs/maui/extensions/keyboard-extensions.md @@ -53,7 +53,7 @@ The following example shows how to check if the Soft Input Keyboard is currently ```csharp using CommunityToolkit.Maui.Core.Platform; -entry.IsSoftKeyboardShowing() +bool isSoftKeyboardShowing = entry.IsSoftKeyboardShowing(); ``` ## Examples From d1e41831f9b78d820fe42e5b53a0294da3ca7d81 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:06:54 -0700 Subject: [PATCH 44/98] CameraView: the Methods table gives what StartVideoRecording and StopVideoRecording throw and return StopVideoRecordingCommand now reports the failure of StopVideoRecording through MediaCaptureFailed, but the table did not say when StopVideoRecording fails. From ICameraView and the platform managers: it returns Stream.Null when no recording runs (Android, iOS, Mac Catalyst and Windows), throws CameraException on Android, iOS and Mac Catalyst when the recording failed without a usable video, and returns the video recorded until an early end otherwise. The StartVideoRecording rows also name the CameraException that the note under Video Recording already gives. Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 36abc55c..03a7456e 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -848,10 +848,10 @@ The commands let no exception escape. `ICommand.Execute` can't return the task o | `CaptureImage(CancellationToken)` | `Task` | Captures a single image from the camera and returns it. The image is also delivered via the `MediaCaptured` event. Throws a `CameraException` when the capture fails, for example when the preview hasn't started, and raises the `MediaCaptureFailed` event with the same reason. | | `GetAvailableCameras(CancellationToken)` | `ValueTask>` | Retrieves a list of available camera devices on the device. | | `StartCameraPreview(CancellationToken)` | `Task` | Starts displaying the camera preview. A preview that can't start is reported through the `ErrorOccurred` event. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the preview started. | -| `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | -| `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. Throws an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | +| `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. Throws a `CameraException` when the recording can't start, and an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | +| `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. Throws a `CameraException` when the recording can't start, and an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | | `StopCameraPreview()` | `void` | Stops displaying the camera preview, and cancels a start of the preview or of a recording that is still in progress. | -| `StopVideoRecording(CancellationToken)` | `Task` | Stops video recording and returns the recorded `Stream`. | +| `StopVideoRecording(CancellationToken)` | `Task` | Stops video recording and returns the `Stream` that received the video, or `Stream.Null` when no recording runs. On Android, iOS and Mac Catalyst, throws a `CameraException` when the recording failed without a usable video. A recording that the platform ended early returns the video recorded until then. | ## CameraInfo From 7d1da72aa25088ff3b89bf0eed2dc3e0dd519663 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:08:50 -0700 Subject: [PATCH 45/98] UserStoppedTypingBehavior: StoppedTypingTimeThreshold must be 0 or more The PR validates the property (ValidateStoppedTypingTimeThreshold): a negative value, which made Task.Delay throw or never complete, is now ignored and the previous value kept, without an exception, as the remarks of the property say. Co-Authored-By: Claude Opus 5.5 --- docs/maui/behaviors/user-stopped-typing-behavior.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/behaviors/user-stopped-typing-behavior.md b/docs/maui/behaviors/user-stopped-typing-behavior.md index bafeed6b..48fe6ba6 100644 --- a/docs/maui/behaviors/user-stopped-typing-behavior.md +++ b/docs/maui/behaviors/user-stopped-typing-behavior.md @@ -113,7 +113,7 @@ class UserStoppedTypingBehaviorPage : ContentPage | Command | [ICommand](xref:System.Windows.Input.ICommand) | The command to execute when the user has stopped providing input. | | MinimumLengthThreshold | int | The minimum length of the input value required before the command will be executed. | | ShouldDismissKeyboardAutomatically | bool | Indicates whether or not the keyboard should be dismissed automatically. Dismissing the keyboard also removes the focus from the input, and only happens while the input has the focus. | -| StoppedTypingTimeThreshold | int | The time of inactivity in milliseconds after which the command will be executed. | +| StoppedTypingTimeThreshold | int | The time of inactivity in milliseconds after which the command will be executed. It must be 0 or more: a negative value, also from a binding, is ignored, and the property keeps its previous value. | ## Examples From abced5b913d9e6814fb430b2677c35e162e0bb39 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:42:46 -0700 Subject: [PATCH 46/98] Apply suggestion from @TheCodeTraveler --- docs/maui/views/semantic-order-view.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index f0e9f593..e5b9e682 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -7,7 +7,7 @@ ms.date: 10/23/2026 # SemanticOrderView -The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers on Android, iOS and Mac Catalyst, and the keyboard Tab order on Windows, to improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. +The `SemanticOrderView` provides the ability to control the order of VisualElements for screen readers on Android, iOS and MacCatalyst, and the keyboard Tab order on Windows, to improve the Accessibility of an application. This can be particularly useful when building user interfaces in orders differing from the order in which users and screen readers will navigate them. ## Using the SemanticOrderView From a6ddcdd41507f29be043a73c2e0dd11153212fe8 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:04:57 -0700 Subject: [PATCH 47/98] SemanticOrderView: the page description names the Windows Tab order, as the introduction does Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/semantic-order-view.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index e5b9e682..b902f2d8 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -1,7 +1,7 @@ --- title: SemanticOrderView - .NET MAUI Community Toolkit author: bijington -description: The SemanticOrderView provides the ability to control the order of VisualElements for screen readers and improve the Accessibility of an application. +description: The SemanticOrderView provides the ability to control the order of VisualElements for screen readers on Android, iOS and Mac Catalyst, and the keyboard Tab order on Windows, to improve the Accessibility of an application. ms.date: 10/23/2026 --- From fee70eef9406802aaa9522a2f7beee86577f2aec Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 30 Oct 2026 11:11:42 -0700 Subject: [PATCH 48/98] StatusBarBehavior: Android needs 6.0 (API 23); on Android 5.0-5.1 it does nothing The Android tab said only that no changes are needed. Brandon decided on 2026-10-30 to drop Android 5.0-5.1 (API 21-22) for StatusBar and StatusBarBehavior (CommunityToolkit/Maui#3344): both already did nothing there, and StatusBarBehavior is now annotated [SupportedOSPlatform("android23.0")], as StatusBar is. The tab now says that they require Android 6.0 (API 23) or later and do nothing on Android 5.0-5.1, that an app which supports those versions still runs there, and what the compiler reports: warning CA1416 for C# that uses StatusBarBehavior or StatusBar in an app whose minimum Android version is below 23, and none for XAML. Raising the minimum to 23, or checking OperatingSystem.IsIOS() || OperatingSystem.IsAndroidVersionAtLeast(23) first, removes the warning; the Android check alone would skip the behavior on iOS, and a project that treats warnings as errors doesn't build until it does one of them. This was measured with an Android 21 library that references the built CommunityToolkit.Maui: 5 warnings for unguarded C# (the type, its three properties and StatusBar.SetColor), 0 behind the check, 0 for a page that declares the behavior in XAML, and 0 with minimum 23. Co-Authored-By: Claude Opus 5.5 --- docs/maui/behaviors/statusbar-behavior.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/maui/behaviors/statusbar-behavior.md b/docs/maui/behaviors/statusbar-behavior.md index 79076eb8..e0008d78 100644 --- a/docs/maui/behaviors/statusbar-behavior.md +++ b/docs/maui/behaviors/statusbar-behavior.md @@ -2,7 +2,7 @@ title: StatusBarBehavior - .NET MAUI Community Toolkit author: pictos description: "The StatusBarBehavior provides the ability to customize the color and style of a device's status bar." -ms.date: 10/23/2026 +ms.date: 10/30/2026 --- # StatusBarBehavior @@ -92,6 +92,11 @@ class MyPage : ContentPage No changes needed. +> [!IMPORTANT] +> Requires Android 6.0 (API 23) or later; on Android 5.0-5.1 (API 21-22) it does nothing. An app that supports those versions still runs on them, but its status bar keeps the default color and style there. +> +> In C#, an app whose minimum Android version is below 23 gets warning CA1416 for code that uses `StatusBarBehavior` or `StatusBar`, and a project that treats warnings as errors doesn't build. Raise the minimum Android version of the app to 23, or put that code inside `if (OperatingSystem.IsIOS() || OperatingSystem.IsAndroidVersionAtLeast(23))`. Don't check `OperatingSystem.IsAndroidVersionAtLeast(23)` alone in code that also runs on iOS: it's `false` on iOS, so the status bar wouldn't change there. XAML doesn't get the warning. + To apply the status bar color and style of the activity to modal pages as well, see [Dialog Fragment Service](../platform-specific/DialogFragment-customization.md). That page also describes how the content of a modal page extends behind the status bar, and how to keep it clear of the status bar. # [iOS](#tab/ios) From 1ac80cdc4aa44a6bf0ca8d287463f27874360bb3 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:12:37 -0800 Subject: [PATCH 49/98] SemanticOrderView: document the Windows Tab order details (duplicates, null ViewOrder, hidden parts, app-set TabIndex) Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/semantic-order-view.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index b902f2d8..040a22b9 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -2,7 +2,7 @@ title: SemanticOrderView - .NET MAUI Community Toolkit author: bijington description: The SemanticOrderView provides the ability to control the order of VisualElements for screen readers on Android, iOS and Mac Catalyst, and the keyboard Tab order on Windows, to improve the Accessibility of an application. -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # SemanticOrderView @@ -66,6 +66,14 @@ The views that aren't in `ViewOrder` stay accessible on every platform. On Windows, the views of `ViewOrder` that the `SemanticOrderView` holds come first among the Tab stops of the `SemanticOrderView`, in the order of `ViewOrder`, followed by the rest of its content in the order of the visual tree. The Tab key reaches the controls above the `SemanticOrderView` before these views, and the controls below it after them. A view of `ViewOrder` that is inside a control within the `SemanticOrderView`, such as a `ScrollView`, or outside of the `SemanticOrderView`, gets a `TabIndex` instead. That `TabIndex` orders it among the Tab stops of the nearest control that holds it. +The `SemanticOrderView` builds its Tab order from `ViewOrder` each time the Tab key moves the focus, so a change to `ViewOrder` applies to the next key press. A few details of the Tab order on Windows: + +- A view that appears more than once in `ViewOrder` is a Tab stop once, at its first position. A `ViewOrder` that is `null`, for example through a binding that hasn't resolved yet, orders nothing. +- A view in a part of the `SemanticOrderView` that isn't visible isn't a Tab stop until that part is visible. +- A view that another view of `ViewOrder` holds is reached through that view. +- A `TabIndex` that your app sets on a view that the `SemanticOrderView` holds isn't overwritten. +- Without a `ViewOrder`, the views keep the default Tab order of Windows. + ## Examples You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/SemanticOrderView/). From fbd0dad1be7ecef3ae788f6ead98019fcc36b31b Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:12:37 -0800 Subject: [PATCH 50/98] Expander: name the not enabled state and the per-state expand/collapse action in the accessibility table Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Expander.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index ac3f2b29..af53bb77 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -2,7 +2,7 @@ title: Expander - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Expander control provides an expandable container to host any content." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Expander @@ -133,9 +133,9 @@ Keyboard and screen reader users can expand and collapse an `Expander` through i |Platform |Behavior | |---------|---------| -| Windows | The `Expander` is a Tab stop. Enter toggles it when it is pressed and Space when it is released, like a `Button`. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | -| Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand or collapse action in its actions menu. A double tap with TalkBack still taps the `Header`, which toggles the `Expander`. | -| iOS and Mac Catalyst | VoiceOver reads the whole `Header` as one button that a double tap toggles. The element has the button trait, and the header trait when the `Header` is a heading. Its label, hint and `AutomationId` come from the `Header`. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A `Header` that holds a control, such as a `Button`, a `Switch` or an `Entry`, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the `Expander` for it. A `Header` with another `TapGestureRecognizer` lets VoiceOver tap it, so that every recognizer runs. | +| Windows | The `Expander` is a Tab stop. Enter toggles it when it is pressed and Space when it is released, like a `Button`. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. The button is disabled while a tap can't toggle the `Expander`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | +| Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand action in its actions menu while the `Expander` is collapsed, and the collapse action while it is expanded. A double tap with TalkBack still taps the `Header`, which toggles the `Expander`. | +| iOS and Mac Catalyst | VoiceOver reads the whole `Header` as one button that a double tap toggles. The element has the button trait, the header trait when the `Header` is a heading, and the not enabled trait while a tap can't toggle the `Expander`. Its label, hint and `AutomationId` come from the `Header`. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A `Header` that holds a control, such as a `Button`, a `Switch` or an `Entry`, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the `Expander` for it. A `Header` with another `TapGestureRecognizer` lets VoiceOver tap it, so that every recognizer runs. | Every activation from the keyboard or from assistive technology goes through the same code as a tap, so `IsExpanded`, `Command` and `CommandParameter`, `ExpandedChanged` and `HandleHeaderTapped` behave as for a tap. In a `CollectionView` on Windows, such an activation still resizes the item that holds the `Expander`. From 126fba3a2b9ed1c80f8d53f1938aae57719ccd00 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:12:37 -0800 Subject: [PATCH 51/98] DialogFragmentService: only Colors.Transparent counts as transparent for the default light status bars Co-Authored-By: Claude Opus 5.5 --- docs/maui/platform-specific/DialogFragment-customization.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index 9c2fe5b7..ccff60c0 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -2,7 +2,7 @@ title: Dialog Fragment Service - .NET MAUI Community Toolkit author: pictos description: The DialogFragmentService provides an easy way to control the behavior of Modal pages in Android. -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Dialog Fragment Service @@ -37,6 +37,8 @@ There will be cases where you want to fix and customize the `DialogFragment` to When a dialog fragment of the activity starts, such as the one that .NET MAUI shows a modal page in, the `DialogFragmentService` gives the window of its dialog the status bar color of the activity's window and, from Android 11 on, its light status bars appearance. Whatever that color is, the dialog's window is laid out like the toolkit lays out the activity's window: the content of the modal page extends behind the system bars, and the page receives the window insets that it uses to keep clear of them. +Only `Colors.Transparent` (`#00000000`) counts as transparent for the default light status bars that the dialog gets when the activity's window has no insets controller. A color with an alpha of 0 and another hue, such as `#00FF0000`, is treated like any other color. + Earlier versions laid the dialog out differently depending on the status bar color. With a color that wasn't transparent, the system padded the content below the status bar. On Android 10 and older, a transparent color gave the page no window insets at all. A modal page that relied on the old padding must now keep clear of the status bar itself, with the safe area. For example, set the `SafeAreaEdges` of the page: ```csharp From 1cac27522b9c91a781f0a2cd68104708a5cfbb54 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:21:20 -0800 Subject: [PATCH 52/98] Maps: deprecate CommunityToolkit.Maui.Maps on the Map page Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Map.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index 0d6f083c..dbf6493d 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -2,16 +2,15 @@ title: Map - .NET MAUI Community Toolkit author: jfversluis description: "The Map control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Map The `Map` control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit. -> [!IMPORTANT] -> Bing Maps has stopped giving out new API keys that are needed for this control to work. We are currently deciding if we should update this control to use the WinUI control that uses Azure Maps or that we will wait for the official .NET MAUI first-party implementation for this. -> For the time being that means you cannot use this control if you do not already have a Bing Maps API key. Bing Maps as a whole will be discontinued entirely on June 30th, 2025. +> [!WARNING] +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Bing Maps, which this library uses to implement `Map` on Windows, has been retired: Bing Maps for Enterprise free (Basic) accounts ended on June 30th, 2025, and Enterprise accounts can continue to use it until June 30th, 2028. Bing Maps no longer issues new API keys, so you cannot use this control on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). ## Setup From d75117887d52f3eb3d60440b7a2b4e36660e6262 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:21:21 -0800 Subject: [PATCH 53/98] Maps: deprecate CommunityToolkit.Maui.Maps on the Get Started page Co-Authored-By: Claude Opus 5.5 --- docs/maui/get-started.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index 7464d3e8..6173d5b6 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -2,7 +2,7 @@ title: Getting Started with the .NET Multi-platform App UI (.NET MAUI) Community Toolkit author: bijington description: The toolkit is available as a set of NuGet packages that can be added to any existing or new .NET MAUI project. -ms.date: 01/23/2023 +ms.date: 11/05/2026 --- # Getting Started with the .NET Multi-platform App UI (.NET MAUI) Community Toolkit @@ -79,9 +79,8 @@ To use the features of the toolkit please refer to the documentation pages for e This package enables you to display a map in your .NET MAUI Windows application. -> [!IMPORTANT] -> Bing Maps has stopped giving out new API keys that are needed for this control to work. We are currently deciding if we should update this control to use the WinUI control that uses Azure Maps or that we will wait for the official .NET MAUI first-party implementation for this. -> For the time being that means you cannot use this control if you do not already have a Bing Maps API key. Bing Maps as a whole will be discontinued entirely on June 30th, 2025. +> [!WARNING] +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Bing Maps, which this library uses to implement `Map` on Windows, has been retired: Bing Maps for Enterprise free (Basic) accounts ended on June 30th, 2025, and Enterprise accounts can continue to use it until June 30th, 2028. Bing Maps no longer issues new API keys, so you cannot use this control on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). **Package name:** `CommunityToolkit.Maui.Maps` From e58e4949c5497f828d001319d672fa6aa284ed04 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:21:21 -0800 Subject: [PATCH 54/98] DrawingView: document pointer handling and rounded image size Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/DrawingView.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/maui/views/DrawingView.md b/docs/maui/views/DrawingView.md index 27fe9929..0bf724ee 100644 --- a/docs/maui/views/DrawingView.md +++ b/docs/maui/views/DrawingView.md @@ -2,7 +2,7 @@ title: DrawingView - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The DrawingView allows to draw lines, save the image and restore it by settings the list of lines." -ms.date: 04/14/2022 +ms.date: 11/05/2026 --- # DrawingView @@ -91,6 +91,9 @@ The following example will export the drawing to an image at a desired width of await drawingView.GetImageStream(desiredWidth: 400, desiredHeight: 300); ``` +> [!NOTE] +> The size of the saved image is rounded to the nearest pixel on every platform. Earlier versions on Android, iOS and Mac Catalyst could give a size one pixel smaller than requested. + > [!NOTE] > By default the `GetImageStream` method will return an image that contains the lines drawn, this will not match the full surface that user sees. In order to generate an image that directly matches the surface displayed in the application the `GetImageStream` method with the `DrawingViewOutputOption` parameter must be used. @@ -124,6 +127,13 @@ await using var stream = await DrawingViewService.GetImageStream( For the purpose of this example the `CanvasWidth` and `CanvasHeight` properties have been data bound to the `Width` and `Height` properties of the `DrawingView` respectively. For the full solution please refer to the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/DrawingViewPage.xaml). +## Pointer handling + +On every platform, a line follows the first touch or pointer that started it. A line that is released outside the `DrawingView` still ends with `DrawingLineCompleted`. If the system takes the pointer away, the line ends with `DrawingLineCancelled`. + +> [!NOTE] +> Earlier versions of the Windows `DrawingView` never ended a line that was released outside the view, and a second pointer (a palm or a pen) started a new line that replaced the first. Apps that handled these cases themselves can remove that code. + ## Handle event when Drawing Line Completed `DrawingView` allows to subscribe to the events like `OnDrawingLineCompleted`. The corresponding command `DrawingLineCompletedCommand` is also available. From 02b2968bbcce5e61757c5548557ab7aecab234da Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:21:25 -0800 Subject: [PATCH 55/98] Maps: mark Map as deprecated in the table of contents Co-Authored-By: Claude Opus 5.5 --- docs/maui/TOC.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml index 100e6c31..412a1689 100644 --- a/docs/maui/TOC.yml +++ b/docs/maui/TOC.yml @@ -233,7 +233,7 @@ items: href: views/Expander.md - name: "LazyView" href: views/LazyView.md - - name: "Map (Windows)" + - name: "Map (Windows) (Deprecated)" href: views/Map.md - name: "MediaElement" href: views/MediaElement.md From 14c0031b9e8f25f59cf4caa1a1b19bc51ccf2b6e Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:23:15 -0800 Subject: [PATCH 56/98] SemanticOrderView: correct the Windows Tab order details (TabIndex, binding example, held views, when a new ViewOrder applies) Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/semantic-order-view.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/semantic-order-view.md b/docs/maui/views/semantic-order-view.md index 040a22b9..c783fb6f 100644 --- a/docs/maui/views/semantic-order-view.md +++ b/docs/maui/views/semantic-order-view.md @@ -66,12 +66,12 @@ The views that aren't in `ViewOrder` stay accessible on every platform. On Windows, the views of `ViewOrder` that the `SemanticOrderView` holds come first among the Tab stops of the `SemanticOrderView`, in the order of `ViewOrder`, followed by the rest of its content in the order of the visual tree. The Tab key reaches the controls above the `SemanticOrderView` before these views, and the controls below it after them. A view of `ViewOrder` that is inside a control within the `SemanticOrderView`, such as a `ScrollView`, or outside of the `SemanticOrderView`, gets a `TabIndex` instead. That `TabIndex` orders it among the Tab stops of the nearest control that holds it. -The `SemanticOrderView` builds its Tab order from `ViewOrder` each time the Tab key moves the focus, so a change to `ViewOrder` applies to the next key press. A few details of the Tab order on Windows: +A new `ViewOrder` applies from the next press of the Tab key. A few details of the Tab order on Windows: -- A view that appears more than once in `ViewOrder` is a Tab stop once, at its first position. A `ViewOrder` that is `null`, for example through a binding that hasn't resolved yet, orders nothing. +- A view that appears more than once in `ViewOrder` is a Tab stop once, at its first position. A `ViewOrder` that is `null`, for example through a binding to a property whose value is still `null`, orders nothing. - A view in a part of the `SemanticOrderView` that isn't visible isn't a Tab stop until that part is visible. -- A view that another view of `ViewOrder` holds is reached through that view. -- A `TabIndex` that your app sets on a view that the `SemanticOrderView` holds isn't overwritten. +- A view that another view of `ViewOrder` holds is reached inside that view, at that view's position in `ViewOrder` rather than at its own. +- The `SemanticOrderView` sets a `TabIndex` only on the views of `ViewOrder` that are inside a control within it, such as a `ScrollView`, or outside of it, and that `TabIndex` replaces one that your app set. A `TabIndex` that your app sets on any other view isn't overwritten. It still applies, and orders that view among the Tab stops of the nearest control that holds it, as a `TabIndex` does without a `SemanticOrderView`. - Without a `ViewOrder`, the views keep the default Tab order of Windows. ## Examples From 44bf435edd923b34b2773428ac580bf479d1a67a Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:23:15 -0800 Subject: [PATCH 57/98] Revert the DialogFragmentService transparent-status-bar paragraph (behavior equals main; never documented before) Co-Authored-By: Claude Opus 5.5 --- docs/maui/platform-specific/DialogFragment-customization.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/maui/platform-specific/DialogFragment-customization.md b/docs/maui/platform-specific/DialogFragment-customization.md index ccff60c0..9c2fe5b7 100644 --- a/docs/maui/platform-specific/DialogFragment-customization.md +++ b/docs/maui/platform-specific/DialogFragment-customization.md @@ -2,7 +2,7 @@ title: Dialog Fragment Service - .NET MAUI Community Toolkit author: pictos description: The DialogFragmentService provides an easy way to control the behavior of Modal pages in Android. -ms.date: 11/05/2026 +ms.date: 10/23/2026 --- # Dialog Fragment Service @@ -37,8 +37,6 @@ There will be cases where you want to fix and customize the `DialogFragment` to When a dialog fragment of the activity starts, such as the one that .NET MAUI shows a modal page in, the `DialogFragmentService` gives the window of its dialog the status bar color of the activity's window and, from Android 11 on, its light status bars appearance. Whatever that color is, the dialog's window is laid out like the toolkit lays out the activity's window: the content of the modal page extends behind the system bars, and the page receives the window insets that it uses to keep clear of them. -Only `Colors.Transparent` (`#00000000`) counts as transparent for the default light status bars that the dialog gets when the activity's window has no insets controller. A color with an alpha of 0 and another hue, such as `#00FF0000`, is treated like any other color. - Earlier versions laid the dialog out differently depending on the status bar color. With a color that wasn't transparent, the system padded the content below the status bar. On Android 10 and older, a transparent color gave the page no window insets at all. A modal page that relied on the old padding must now keep clear of the status bar itself, with the safe area. For example, set the `SafeAreaEdges` of the page: ```csharp From 26695947697d97ea912cd68ac11d2ce6b75d1cd9 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:42:33 -0800 Subject: [PATCH 58/98] Maps and DrawingView docs: name the .NET MAUI Map as the replacement, scope the pointer and image-size notes to what the code does, fix the API link Co-Authored-By: Claude Opus 5.5 --- docs/maui/get-started.md | 4 +++- docs/maui/views/DrawingView.md | 4 ++-- docs/maui/views/Map.md | 10 ++++++---- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index 6173d5b6..0a46cbb1 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -80,7 +80,9 @@ To use the features of the toolkit please refer to the documentation pages for e This package enables you to display a map in your .NET MAUI Windows application. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Bing Maps, which this library uses to implement `Map` on Windows, has been retired: Bing Maps for Enterprise free (Basic) accounts ended on June 30th, 2025, and Enterprise accounts can continue to use it until June 30th, 2028. Bing Maps no longer issues new API keys, so you cannot use this control on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. It implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this control on Windows without an existing key. +> +> Starting with .NET MAUI 10.0.70, the .NET MAUI `Map` supports Windows with Azure Maps. To move to it, remove the call to `UseMauiCommunityToolkitMaps`, call `UseMauiMaps` on every platform, and set your Azure Maps key with `UseMapServiceToken`. For more information, see [Map](/dotnet/maui/user-interface/controls/map) and [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). **Package name:** `CommunityToolkit.Maui.Maps` diff --git a/docs/maui/views/DrawingView.md b/docs/maui/views/DrawingView.md index 0bf724ee..6e920f1d 100644 --- a/docs/maui/views/DrawingView.md +++ b/docs/maui/views/DrawingView.md @@ -92,7 +92,7 @@ await drawingView.GetImageStream(desiredWidth: 400, desiredHeight: 300); ``` > [!NOTE] -> The size of the saved image is rounded to the nearest pixel on every platform. Earlier versions on Android, iOS and Mac Catalyst could give a size one pixel smaller than requested. +> When the image is scaled to fit the desired size, its size is rounded to whole pixels, so the side that limits the scale is exactly the desired size on Android, iOS, Mac Catalyst and Windows. On Android, earlier versions could give an image one pixel smaller than the desired size. > [!NOTE] > By default the `GetImageStream` method will return an image that contains the lines drawn, this will not match the full surface that user sees. In order to generate an image that directly matches the surface displayed in the application the `GetImageStream` method with the `DrawingViewOutputOption` parameter must be used. @@ -129,7 +129,7 @@ For the purpose of this example the `CanvasWidth` and `CanvasHeight` properties ## Pointer handling -On every platform, a line follows the first touch or pointer that started it. A line that is released outside the `DrawingView` still ends with `DrawingLineCompleted`. If the system takes the pointer away, the line ends with `DrawingLineCancelled`. +A line that is released outside the `DrawingView` still ends with `DrawingLineCompleted`. If the system takes the pointer away, the line ends with `DrawingLineCancelled`. On Windows, a line follows the pointer that started it: while it is drawn, another pointer (a second finger, a palm or a pen) doesn't start a new line and doesn't extend, end or cancel the line. > [!NOTE] > Earlier versions of the Windows `DrawingView` never ended a line that was released outside the view, and a second pointer (a palm or a pen) started a new line that replaced the first. Apps that handled these cases themselves can remove that code. diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index dbf6493d..2baa4288 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -1,16 +1,18 @@ --- title: Map - .NET MAUI Community Toolkit author: jfversluis -description: "The Map control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit." +description: "The Map control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps." ms.date: 11/05/2026 --- # Map -The `Map` control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit. +The `Map` control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Bing Maps, which this library uses to implement `Map` on Windows, has been retired: Bing Maps for Enterprise free (Basic) accounts ended on June 30th, 2025, and Enterprise accounts can continue to use it until June 30th, 2028. Bing Maps no longer issues new API keys, so you cannot use this control on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. It implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this control on Windows without an existing key. +> +> Starting with .NET MAUI 10.0.70, the .NET MAUI `Map` supports Windows with Azure Maps. To move to it, remove the call to `UseMauiCommunityToolkitMaps`, call `UseMauiMaps` on every platform, and set your Azure Maps key with `UseMapServiceToken`. For more information, see [Map](/dotnet/maui/user-interface/controls/map) and [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). ## Setup @@ -43,4 +45,4 @@ You can find examples of this control in action in the [.NET MAUI Community Tool ## API -You can find the source code for `Map` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui.Maps/AppHostBuilderExtensions.shared.cs). +You can find the source code for `Map` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui.Maps/AppBuilderExtensions.shared.cs). From b12a50bae8fc81dfa0f6a8255d36857232abdec0 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:43:59 -0800 Subject: [PATCH 59/98] Maps docs: recommend Microsoft.Maui.Controls.Maps (Windows since .NET MAUI 10) with the Azure Maps key setup and the Windows limitations Co-Authored-By: Claude Opus 5.5 --- docs/maui/get-started.md | 8 ++++++-- docs/maui/views/Map.md | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index 0a46cbb1..03c6ff7c 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -80,9 +80,13 @@ To use the features of the toolkit please refer to the documentation pages for e This package enables you to display a map in your .NET MAUI Windows application. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. It implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this control on Windows without an existing key. +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. It uses the WinUI 3 `MapControl`, which is backed by Azure Maps. > -> Starting with .NET MAUI 10.0.70, the .NET MAUI `Map` supports Windows with Azure Maps. To move to it, remove the call to `UseMauiCommunityToolkitMaps`, call `UseMauiMaps` on every platform, and set your Azure Maps key with `UseMapServiceToken`. For more information, see [Map](/dotnet/maui/user-interface/controls/map) and [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> To move to it, remove the call to `UseMauiCommunityToolkitMaps` and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"));`; without a valid key the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). +> +> On Windows, the .NET MAUI `Map` doesn't support `IsShowingUser`, polygons, polylines and circles in `MapElements`, pin labels and info windows, or the `MapClicked` event. It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> +> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this library on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). **Package name:** `CommunityToolkit.Maui.Maps` diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index 2baa4288..f6775e17 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -10,9 +10,13 @@ ms.date: 11/05/2026 The `Map` control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. It implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this control on Windows without an existing key. +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. It uses the WinUI 3 `MapControl`, which is backed by Azure Maps. > -> Starting with .NET MAUI 10.0.70, the .NET MAUI `Map` supports Windows with Azure Maps. To move to it, remove the call to `UseMauiCommunityToolkitMaps`, call `UseMauiMaps` on every platform, and set your Azure Maps key with `UseMapServiceToken`. For more information, see [Map](/dotnet/maui/user-interface/controls/map) and [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> To move to it, remove the call to `UseMauiCommunityToolkitMaps` and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"));`; without a valid key the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). +> +> On Windows, the .NET MAUI `Map` doesn't support `IsShowingUser`, polygons, polylines and circles in `MapElements`, pin labels and info windows, or the `MapClicked` event. It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> +> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this library on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). ## Setup From bf190c606c117874477dbb1e46dadfa046ec72df Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:11:14 -0800 Subject: [PATCH 60/98] Maps docs: add the package swap step, scope the MapControl sentence to Windows, drop the unverified Bing key claim, list the Windows limitations Co-Authored-By: Claude Opus 5.5 --- docs/maui/get-started.md | 15 +++++++++++---- docs/maui/views/Map.md | 15 +++++++++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index 03c6ff7c..7f1543ce 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -80,13 +80,20 @@ To use the features of the toolkit please refer to the documentation pages for e This package enables you to display a map in your .NET MAUI Windows application. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. It uses the WinUI 3 `MapControl`, which is backed by Azure Maps. +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. On Windows, it uses the WinUI 3 `MapControl`, which is backed by Azure Maps. > -> To move to it, remove the call to `UseMauiCommunityToolkitMaps` and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"));`; without a valid key the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). +> To move to it, remove the `CommunityToolkit.Maui.Maps` package and make sure your project references the `Microsoft.Maui.Controls.Maps` package directly, because `CommunityToolkit.Maui.Maps` referenced it for you. Remove `using CommunityToolkit.Maui.Maps;` and the call to `UseMauiCommunityToolkitMaps`, and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"))`. Without a valid key, the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). > -> On Windows, the .NET MAUI `Map` doesn't support `IsShowingUser`, polygons, polylines and circles in `MapElements`, pin labels and info windows, or the `MapClicked` event. It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> On Windows, the .NET MAUI `Map` doesn't support: > -> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this library on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> - `IsShowingUser` +> - Polygons, polylines and circles in `MapElements` +> - Pin labels and info windows +> - The `MapClicked` event +> +> It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> +> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). **Package name:** `CommunityToolkit.Maui.Maps` diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index f6775e17..4bb76035 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -10,13 +10,20 @@ ms.date: 11/05/2026 The `Map` control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. It uses the WinUI 3 `MapControl`, which is backed by Azure Maps. +> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. On Windows, it uses the WinUI 3 `MapControl`, which is backed by Azure Maps. > -> To move to it, remove the call to `UseMauiCommunityToolkitMaps` and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"));`; without a valid key the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). +> To move to it, remove the `CommunityToolkit.Maui.Maps` package and make sure your project references the `Microsoft.Maui.Controls.Maps` package directly, because `CommunityToolkit.Maui.Maps` referenced it for you. Remove `using CommunityToolkit.Maui.Maps;` and the call to `UseMauiCommunityToolkitMaps`, and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"))`. Without a valid key, the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). > -> On Windows, the .NET MAUI `Map` doesn't support `IsShowingUser`, polygons, polylines and circles in `MapElements`, pin labels and info windows, or the `MapClicked` event. It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> On Windows, the .NET MAUI `Map` doesn't support: > -> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. Bing Maps no longer issues new API keys, so you can't use this library on Windows without an existing key. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). +> - `IsShowingUser` +> - Polygons, polylines and circles in `MapElements` +> - Pin labels and info windows +> - The `MapClicked` event +> +> It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. +> +> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). ## Setup From 9b04c50fe931bee89429fa144ae6d7885356dcee Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:38:25 -0800 Subject: [PATCH 61/98] CameraView: document how a recording starts and ends (join, replace, auto-start, Windows stop, restore failure) and move the start note away from #669's spot Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 03a7456e..29ad550c 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -2,7 +2,7 @@ title: CameraView - .NET MAUI Community Toolkit author: bijington description: "The CameraView provides the ability to connect to a camera, display a preview from the camera, take photos, and record videos." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # CameraView @@ -541,6 +541,19 @@ The following example shows how to add a `Button` into the application and setup > [!NOTE] > You must provide a clean stream in order to record the video. +> [!NOTE] +> `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). + +### How a recording starts and ends + +- **A second start joins the first.** A `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. +- **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`. On Android, iOS and Mac Catalyst, the recording that ran before ends and its video is discarded. Earlier versions on Android ignored the second start and kept the first recording. +- **The camera is released while a start waits.** When the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. +- **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. +- **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. +- **Stopping the preview ends the recording.** On Windows, `StopCameraPreview` while a recording runs ends the recording, and a later `StopVideoRecording` returns `Stream.Null`. +- **A failure to restore the camera after saving.** On Android, the camera switches to a video session for the recording and back to the photo session afterwards. When that switch back fails after the video was written, `StopVideoRecording` still returns the video, and the failure is reported through the `ErrorOccurred` event. + The following example demonstrates how to use the `StartVideoRecording` method: > [!NOTE] @@ -597,9 +610,6 @@ async void StartCameraRecording(object? sender, EventArgs e) } ``` -> [!NOTE] -> `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). - ## Start preview The `CameraView` provides the ability to programmatically start the preview from the camera. This is possible through both the `StartCameraPreview` method or the `StartCameraPreviewCommand`. @@ -692,12 +702,16 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, and an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected. +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and the exception of another start that it waited for and that failed (see below). ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); ``` +Each failure raises `ErrorOccurred` once. A `StartCameraPreview` that waits for another start, for example while the `CameraView` connects to its camera, and that start fails, throws the exception to its caller instead, and raises no second event. + +On Windows, a `StartCameraPreview` while the preview runs does nothing. A restart of the preview releases the camera that the earlier start held. + What happens next depends on why the start failed: - **The selected camera can't be opened.** The preview stays stopped, but it follows `SelectedCamera`: selecting another camera starts the preview with that camera. This holds until `StopCameraPreview` is called. @@ -802,7 +816,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) - A camera switch, which is a change of `SelectedCamera`. - On Android, the restart of the preview for a new `ImageCaptureResolution`, and the automatic start that waits for the camera permission. -None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` again. +None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` or `StartVideoRecording` again. On Windows, `StartVideoRecording` doesn't start the preview: call `StartCameraPreview`. A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when your app calls `StopCameraPreview` in `OnDisappearing`, or from a stop button, while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. On Windows, a `StartCameraPreview` that its own token cancels after the camera has opened stops the preview that it had shown, and releases the camera. @@ -839,7 +853,7 @@ The commands let no exception escape. `ICommand.Execute` can't return the task o |---------|---------|---------| | `MediaCaptured` | `EventHandler` | Raised when an image is successfully captured. The `MediaCapturedEventArgs` contains a `Media` property of type `Stream` with the captured image data. | | `MediaCaptureFailed` | `EventHandler` | Raised when an image capture fails, and when `StartVideoRecordingCommand` or `StopVideoRecordingCommand` fails. The `MediaCaptureFailedEventArgs` contains a `FailureReason` property with the error message. | -| `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. | +| `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. Each failure is reported once. On Android, it is also raised when the camera can't switch back to the photo session after `StopVideoRecording` has exported the video. | ## Methods From 2cc05495a4f8109f46ea09e46c97894331c0e87c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:38:25 -0800 Subject: [PATCH 62/98] Popup: ShowPopupAsync completes as dismissed and Closed is raised when navigation removes the PopupPage; a popup shown from OnDisappearing Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Popup.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index f31561cd..93714d21 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -2,7 +2,7 @@ title: Popup - .NET MAUI Community Toolkit author: bijington description: The Popup view allows developers to build their own custom UI and present it to their users. -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Popup @@ -180,6 +180,10 @@ public class MyPage : ContentPage By default a user can tap outside of the `Popup` to dismiss it. This can be controlled through the use of the `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` property, or the `CanBeDismissedByTappingOutsideOfPopup` property of the `Popup`. Setting either property to `false` will prevent a user from being able to dismiss the `Popup` by tapping outside of it: the `Popup` is dismissed only while both are `true`. See [PopupOptions](./popup/popup-options.md) for more details. +### Navigation removes the Popup + +A `Popup` is displayed on a modal page, so navigation can remove it without a call to `CloseAsync`. For example, Shell navigates to another route, other code calls `PopModalAsync`, or the `Page` of the `Window` is replaced. The task that `ShowPopupAsync` returned then completes with an `IPopupResult` whose `WasDismissedByTappingOutsideOfPopup` is `true`, like when the user dismisses the `Popup` by tapping outside of it, and `Closed` is raised once. Earlier versions left that task pending and never raised `Closed`. + ## Lifecycle behavior It is important to note that a `Popup` will be displayed inside `ContentPage` which is then shown modally in a .NET MAUI application. The impact of this will result in any calling `Page` to have the following lifecycle events to be called: @@ -228,6 +232,8 @@ protected override void OnNavigatedFrom(NavigatedFromEventArgs args) } ``` +When you show a `Popup` from `OnDisappearing` of a modal page that is being removed, for example after `PopModalAsync`, the `Popup` is displayed once the modal page has been removed, on the page below it. + ## PopupOptions The `PageOverlayColor`, `Shape`, `Shadow` can all be customized for Popup. See [PopupOptions](./popup/popup-options.md) for more details. @@ -331,7 +337,7 @@ The `Popup` class provides the following events that can be subscribed to. |Event | Description | |---------|---------| -| `Closed` | Occurs when the `Popup` is closed. | +| `Closed` | Occurs when the `Popup` is closed, also when navigation removes it without a call to `CloseAsync`. It is raised once. | | `Opened` | Occurs when the `Popup` is opened. It is raised once each time the `Popup` is shown, and not again when a page or another `Popup` that was displayed above it is closed. | ## Examples From 54e2d28a91138d96fd3eece0eacd8c2dc284059b Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:38:25 -0800 Subject: [PATCH 63/98] Toast and Snackbar: on Windows each removes only its own notification; Snackbar Duration below 1 ms on Android Co-Authored-By: Claude Opus 5.5 --- docs/maui/alerts/snackbar.md | 6 +++--- docs/maui/alerts/toast.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/maui/alerts/snackbar.md b/docs/maui/alerts/snackbar.md index 25252e7e..442f6d37 100644 --- a/docs/maui/alerts/snackbar.md +++ b/docs/maui/alerts/snackbar.md @@ -2,7 +2,7 @@ title: Snackbar - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Snackbar is a timed alert that appears at the bottom of the screen by default." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Snackbar @@ -93,7 +93,7 @@ Snackbar.Dismissed += (s, e) => { Console.WriteLine(Snackbar.IsShown); }; | Action | `Action` | Action to invoke on action button click. | | ActionButtonText | `string` | Action button text. | | Anchor | `IView` | `Snackbar` anchor. `Snackbar` appears near this view. When `null`, the `Snackbar` will appear at the bottom of the screen. | -| Duration | `TimeSpan` | `Snackbar` duration. | +| Duration | `TimeSpan` | `Snackbar` duration. On Android, a `Duration` below 1 millisecond is shown for 1 millisecond, so the `Snackbar` goes away at once, as on the other platforms. | | VisualOptions | `SnackbarOptions` | `Snackbar` visual options. | ### SnackbarOptions @@ -122,7 +122,7 @@ The `SnackbarOptions` allows you to customize the default `Snackbar` style. > [!NOTE] > You can display only 1 `Snackbar` at the same time. If you call the `Show` method a second time, the first `Snackbar` will automatically be dismissed before the second `Snackbar` is shown. -On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called, and the `Shown` and `Dismissed` events are raised in that order. A `Snackbar` that a later call replaced or dismissed doesn't stay on screen. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Snackbar` throws an `OperationCanceledException` and removes nothing. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called, and the `Shown` and `Dismissed` events are raised in that order. A `Snackbar` that a later call replaced or dismissed doesn't stay on screen. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Snackbar` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Snackbar`: the other notifications that your app shows, for example those of a `Toast`, stay. > [!WARNING] > On Windows, a `Show` or `Dismiss` that you call from a `Shown` or `Dismissed` handler runs after the `Show` or `Dismiss` call that raised the event has finished. Await it. Blocking on its `Task` inside the handler, for example with `.Wait()` or `.Result`, deadlocks. diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index c8423f7e..793b4dae 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -2,7 +2,7 @@ title: Toast - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The Toast is a timed alert that appears at the bottom of the screen by default." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Toast @@ -77,7 +77,7 @@ These values adhere to the constants defined in the [`android.widget.Toast` API] > [!NOTE] > You can display only one `Toast` at a time. If you call the `Show` method a second time, the first `Toast` will automatically be dismissed. -On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called: the `Toast` of the last `Show` is the one that is displayed, and a `Dismiss` after it leaves none. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Toast` throws an `OperationCanceledException` and removes nothing. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called: the `Toast` of the last `Show` is the one that is displayed, and a `Dismiss` after it leaves none. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Toast` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Toast`: the other notifications that your app shows, for example those of a `Snackbar`, stay. ## Examples From e4ef209e38c9f3987e0eaaf060fbd83c0554f24a Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:38:25 -0800 Subject: [PATCH 64/98] MediaElement: SeekTo clamping, Play at the end, a source without data Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/MediaElement.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index 0c4bb4c3..e5502174 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -3,7 +3,7 @@ title: MediaElement - .NET MAUI Community Toolkit description: "This article explains how to use MediaElement to play video and audio in a .NET MAUI application." author: jfversluis ms.author: joverslu -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # MediaElement @@ -461,7 +461,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide | ShouldKeepScreenOn | `bool` | Determines whether the device screen should stay on during media playback. This is a bindable property. | `false` | | ShouldMute | `bool` | Determines whether the audio is currently muted. This is a bindable property. | `false` | | ShouldShowPlaybackControls | `bool` | Determines whether the platforms playback controls are displayed. This is a bindable property. Note that on iOS and Windows the controls are only shown for a brief period after interacting with the screen. There is no way of keeping the controls visible at all times. | `true` | -| Source | `MediaSource?` | The source of the media loaded into the control. | `null` | +| Source | `MediaSource?` | The source of the media loaded into the control. A source without data, for example a `UriMediaSource` without a `Uri` or a `StreamMediaSource` without a stream, empties the player and reports `MediaElementState.None`, like a `null` source. | `null` | | Speed | `double` | Determines the playback speed of the media. This is a bindable property. On Windows, a playback rate that the player reports after a newer `Speed` was set doesn't change `Speed` back. | `1` | | MediaHeight | `int` | The height of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | | MediaWidth | `int` | The width of the loaded media in pixels. This is a read-only, bindable property. Not reported for non-visual media and might not always be populated on iOS/macOS for live streamed content. | `0` | @@ -481,10 +481,10 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide |Event |Description | |---------|---------| -| Play | Starts playing the loaded media. | +| Play | Starts playing the loaded media. Media that played to its end starts again from its start. | | Pause | Pauses playback of the current media. | | Stop | Stops playback and resets the position of the current media. | -| SeekTo | Takes a `TimeSpan` value to set the `Position` property to and takes a `CancellationToken` to cancel the `Task`. | +| SeekTo | Takes a `TimeSpan` value to set the `Position` property to and takes a `CancellationToken` to cancel the `Task`. A position outside of the media is clamped to it: a position before the start seeks to the start, and a position beyond `Duration` seeks to the end. The seek then completes and raises `SeekCompleted` like any other. It throws an `InvalidOperationException` when the platform player can't seek yet, for example before it is ready. | ## Examples From 35bd52323854b859ef0f7643dc1cb6d7b33de7c4 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:38:25 -0800 Subject: [PATCH 65/98] NavigationBar, TouchBehavior, validation Flags, ColorAnimation rate, Gravatar, Badge manifest query, keyboard threading: document the behavior changes Co-Authored-By: Claude Opus 5.5 --- docs/maui/behaviors/touch-behavior.md | 4 ++-- docs/maui/essentials/badge.md | 5 ++++- docs/maui/extensions/color-animation-extensions.md | 6 +++--- docs/maui/extensions/keyboard-extensions.md | 4 +++- docs/maui/imagesources/GravatarImageSource.md | 4 ++-- docs/maui/includes/validation-behavior.md | 2 +- docs/maui/platform-specific/navigation-bar.md | 8 +++++++- 7 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/maui/behaviors/touch-behavior.md b/docs/maui/behaviors/touch-behavior.md index e4998c17..d7c7907f 100644 --- a/docs/maui/behaviors/touch-behavior.md +++ b/docs/maui/behaviors/touch-behavior.md @@ -2,7 +2,7 @@ title: TouchBehavior - .NET MAUI Community Toolkit author: bijington description: The TouchBehavior is a Behavior that provides the ability to interact with any VisualElement based on touch, mouse click and hover events. -ms.date: 03/25/2024 +ms.date: 11/05/2026 --- # TouchBehavior @@ -250,7 +250,7 @@ The following example shows how to add the `TouchBehavior` to a `HorizontalStack | PressedScale | `double` | Gets or sets the scale of the element when the `CurrentTouchState` property is `TouchState.Pressed`. | | PressedTranslationX | `double` | Gets or sets the X translation of the element when the `CurrentTouchState` property is `TouchState.Pressed`. | | PressedTranslationY | `double` | Gets or sets the Y translation of the element when the `CurrentTouchState` property is `TouchState.Pressed`. | -| ShouldMakeChildrenInputTransparent | `bool` | Gets or sets a value indicating whether the children of the element should be made input transparent. | +| ShouldMakeChildrenInputTransparent | `bool` | Gets or sets a value indicating whether the children of the element should be made input transparent. A change applies while the behavior is attached: `false` gives each child back the `InputTransparent` value it had. | ## Events diff --git a/docs/maui/essentials/badge.md b/docs/maui/essentials/badge.md index 84d5c405..e255fbdb 100644 --- a/docs/maui/essentials/badge.md +++ b/docs/maui/essentials/badge.md @@ -2,7 +2,7 @@ title: Badge - .NET MAUI Community Toolkit author: VladislavAntonyuk description: The Badge API allows developers to set the app icon badge number on the home screen. -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # Badge @@ -153,4 +153,7 @@ These changes are enough for your application to run on an Android based Samsung Therefore, while our code aims to provide an ideal implementation, there may be instances where Android will not behave as expected. +> [!NOTE] +> `CommunityToolkit.Maui.Core` ships an Android library manifest that adds a `` entry for the `MAIN` action with the `HOME` category to the manifest of your app. From Android 11 (package visibility), the badge can find the launcher only when the app declares this query. You don't need to add it yourself. + We strongly recommend thoroughly testing your app on a range of devices and launchers for the most accurate assessment of how app badge notifications behave in your specific use case. diff --git a/docs/maui/extensions/color-animation-extensions.md b/docs/maui/extensions/color-animation-extensions.md index 9a068b36..73ea4d42 100644 --- a/docs/maui/extensions/color-animation-extensions.md +++ b/docs/maui/extensions/color-animation-extensions.md @@ -2,7 +2,7 @@ title: ColorAnimationExtensions - .NET MAUI Community Toolkit author: bijington description: "The ColorAnimationExtensions provide a series of extension methods that support animating the Color related properties of a VisualElement." -ms.date: 04/22/2022 +ms.date: 11/05/2026 --- # ColorAnimationExtensions @@ -37,7 +37,7 @@ await label.BackgroundColorTo(Colors.Red); The full argument list for the `BackgroundColorTo` method is: - `color`, of type `Color`, is the target color to animate the `VisualElement`'s `BackgroundColor` to. -- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. +- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16 It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. @@ -59,7 +59,7 @@ await label.TextColorTo(Colors.Red); The full argument list for the `TextColorTo` method is: - `color`, of type `Color`, is the target color to animate the `VisualElement`'s `BackgroundColor` to. -- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. +- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16 It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. diff --git a/docs/maui/extensions/keyboard-extensions.md b/docs/maui/extensions/keyboard-extensions.md index e574bfe4..5380fad8 100644 --- a/docs/maui/extensions/keyboard-extensions.md +++ b/docs/maui/extensions/keyboard-extensions.md @@ -2,7 +2,7 @@ title: KeyboardExtensions - .NET MAUI Community Toolkit author: PureWeen description: "The KeyboardExtensions provide a series of extension methods that support interacting with the Keyboard." -ms.date: 10/23/2026 +ms.date: 11/05/2026 --- # KeyboardExtensions @@ -56,6 +56,8 @@ using CommunityToolkit.Maui.Core.Platform; bool isSoftKeyboardShowing = entry.IsSoftKeyboardShowing(); ``` +On iOS and Windows, the state of the keyboard is read on the UI thread. When you call `IsSoftKeyboardShowing` from another thread, it blocks until the UI thread has answered. On the same platforms, `HideKeyboardAsync` and `ShowKeyboardAsync` do their work on the UI thread, and their tasks complete once the UI thread has done it. + ## Examples You can find an example of this extension in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Extensions/KeyboardExtensionsPage.xaml). diff --git a/docs/maui/imagesources/GravatarImageSource.md b/docs/maui/imagesources/GravatarImageSource.md index 5caf8148..9f2ca0f0 100644 --- a/docs/maui/imagesources/GravatarImageSource.md +++ b/docs/maui/imagesources/GravatarImageSource.md @@ -2,7 +2,7 @@ title: GravatarImageSource - .NET MAUI Community Toolkit author: GeorgeLeithead description: "`GravatarImageSource` allows you to use as an Image source, a users Gravatar registered image via their email address." -ms.date: 09/16/2022 +ms.date: 11/05/2026 --- # GravatarImageSource @@ -69,7 +69,7 @@ partial class MyPage : ContentPage |---|---|---| | CacheValidity | `TimeSpan` | The `CacheValidity` property, of type `TimeSpan`, specifies how long the image will be stored locally for. The default value of this property is 1 day. | | CachingEnabled | `bool` | The `CachingEnabled` property, of type `bool`, defines whether image caching is enabled. The default value of this property is `true`. | -| Email | `string?` | The `Email` property, of type `string?`, specifies the gravatar account email address. If unset, the Gravatar image is rendered. If set and not found on Gravatar, the `Image` property image will be rendered. | +| Email | `string?` | The `Email` property, of type `string?`, specifies the gravatar account email address. If unset, the Gravatar image is rendered. If set and not found on Gravatar, the `Image` property image will be rendered. As Gravatar requires, the address is trimmed and converted to lower case before it is hashed, so `" User@Example.com "` and `"user@example.com"` load the same image. The value of the property doesn't change. | | Image | `DefaultImage` | The `Image` property, of type [`DefaultImage`](#set-default-image) is an enumeration that is used to specify the default image if the `email` is not found on Gravatar. | These properties are backed by `BindableProperty` objects, which means that they can be targets of data bindings and styled. diff --git a/docs/maui/includes/validation-behavior.md b/docs/maui/includes/validation-behavior.md index 5c125437..d09e4eaf 100644 --- a/docs/maui/includes/validation-behavior.md +++ b/docs/maui/includes/validation-behavior.md @@ -8,7 +8,7 @@ The following properties are implemented in the base class, `public abstract cla |Property |Type |Description | |---------|---------|---------| -| `Flags` | `ValidationFlags` | Provides an enumerated value that specifies how to handle validation. | +| `Flags` | `ValidationFlags` | Provides an enumerated value that specifies how to handle validation. Once the behavior has validated a value, a change of a validation rule, of `ValidStyle`, of `InvalidStyle` or of `Flags` validates the current `Value` again, whatever the flags, so that `IsValid` follows the current rules. `ForceMakeValidWhenFocused` still keeps a focused view valid. | | `ForceValidateCommand` | `ICommand` | Allows the user to provide a custom `ICommand` that handles forcing validation. | | `InvalidStyle` | `Style` | The `Style` to apply to the element when validation fails. | | `IsNotValid` | `bool` | Indicates whether or not the current value is considered not valid. | diff --git a/docs/maui/platform-specific/navigation-bar.md b/docs/maui/platform-specific/navigation-bar.md index 6384225c..a964c472 100644 --- a/docs/maui/platform-specific/navigation-bar.md +++ b/docs/maui/platform-specific/navigation-bar.md @@ -2,7 +2,7 @@ title: Android NavigationBar - .NET MAUI Community Toolkit author: bijington description: The NavigationBar provides the ability to customize the appearance of the Navigation Bar on the Android platform. -ms.date: 02/15/2024 +ms.date: 11/05/2026 --- # Android NavigationBar @@ -15,6 +15,8 @@ The feature provides the ability to set: The `Color` property makes it possible to provide any [`Color`](xref:Microsoft.Maui.Graphics.Color) to use in setting the background color of the navigation bar. +Before Android 15 (API 35), the color is the navigation bar color of the window. From Android 15 on, Android draws the window behind the navigation bar and ignores that color, so the toolkit shows the color in a view on top of the window that covers the navigation bar: at the bottom, or, with three-button navigation in landscape, at the right or left edge. The view follows the navigation bar when the window rotates, or when the navigation bar is hidden or shown. + ## Bar Style The `Style` property makes it possible to customize the foreground color of the navigation with the following allowed values: @@ -23,6 +25,10 @@ The `Style` property makes it possible to customize the foreground color of the * `LightContent` - the foreground will apply the light theme color. * `DarkContent` - the foreground will apply the dark theme color. +From Android 15 on, when Android enforces edge-to-edge (Android 16 does for every app that targets it), it forces light navigation bars on a window that has a light background and no navigation bar color of its own, whatever the app asks for. Setting a `Style` gives the window a transparent navigation bar color, which stops that: with three-button navigation, Android then draws a scrim behind the navigation bar that matches the style. With gesture navigation, Android may tint the gesture handle to contrast with what is behind it, whatever the style. + +When a page clears its `Color` or `Style` (`ClearValue`), every window that still shows that value gets back the navigation bar color or appearance it had before the `NavigationBar` first changed it. + ## Syntax The following examples show how to use the `NavigationBar` to set the background color to `DarkSlateBlue` and the foreground style to `LightContent`. From cc5a28229861d2ac1ab087d4f1c0a76f6f1dd55d Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:53:48 -0800 Subject: [PATCH 66/98] Docs review fixes: scope the Camera start/stop statements to the platforms whose code implements them, fix a typo, move the examples back under Video Recording Co-Authored-By: Claude Opus 5.5 --- docs/maui/extensions/color-animation-extensions.md | 4 ++-- docs/maui/views/MediaElement.md | 2 +- docs/maui/views/camera-view.md | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/maui/extensions/color-animation-extensions.md b/docs/maui/extensions/color-animation-extensions.md index 73ea4d42..49a6809f 100644 --- a/docs/maui/extensions/color-animation-extensions.md +++ b/docs/maui/extensions/color-animation-extensions.md @@ -37,7 +37,7 @@ await label.BackgroundColorTo(Colors.Red); The full argument list for the `BackgroundColorTo` method is: - `color`, of type `Color`, is the target color to animate the `VisualElement`'s `BackgroundColor` to. -- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16 It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. +- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. @@ -59,7 +59,7 @@ await label.TextColorTo(Colors.Red); The full argument list for the `TextColorTo` method is: - `color`, of type `Color`, is the target color to animate the `VisualElement`'s `BackgroundColor` to. -- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16 It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. +- `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index e5502174..f2509e86 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -481,7 +481,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide |Event |Description | |---------|---------| -| Play | Starts playing the loaded media. Media that played to its end starts again from its start. | +| Play | Starts playing the loaded media. On Android, iOS and Mac Catalyst, media that played to its end starts again from its start. | | Pause | Pauses playback of the current media. | | Stop | Stops playback and resets the position of the current media. | | SeekTo | Takes a `TimeSpan` value to set the `Position` property to and takes a `CancellationToken` to cancel the `Task`. A position outside of the media is clamped to it: a position before the start seeks to the start, and a position beyond `Duration` seeks to the end. The seek then completes and raises `SeekCompleted` like any other. It throws an `InvalidOperationException` when the platform player can't seek yet, for example before it is ready. | diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 29ad550c..00f59df7 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -544,11 +544,11 @@ The following example shows how to add a `Button` into the application and setup > [!NOTE] > `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). -### How a recording starts and ends +A recording starts and ends as follows: -- **A second start joins the first.** A `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. +- **A second start joins the first.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. - **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`. On Android, iOS and Mac Catalyst, the recording that ran before ends and its video is discarded. Earlier versions on Android ignored the second start and kept the first recording. -- **The camera is released while a start waits.** When the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. +- **The camera is released while a start waits.** On Android, iOS and Mac Catalyst, when the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. - **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. - **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. - **Stopping the preview ends the recording.** On Windows, `StopCameraPreview` while a recording runs ends the recording, and a later `StopVideoRecording` returns `Stream.Null`. @@ -702,15 +702,15 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and the exception of another start that it waited for and that failed (see below). +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, the exception of the camera connection that it waited for and that failed (see below). ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); ``` -Each failure raises `ErrorOccurred` once. A `StartCameraPreview` that waits for another start, for example while the `CameraView` connects to its camera, and that start fails, throws the exception to its caller instead, and raises no second event. +Each failure raises `ErrorOccurred` once. On Android, when the camera connection that a `StartCameraPreview` waited for fails, the connection raises `ErrorOccurred`, and `StartCameraPreview` throws the same exception to its caller instead of raising the event a second time. -On Windows, a `StartCameraPreview` while the preview runs does nothing. A restart of the preview releases the camera that the earlier start held. +On Windows, a `StartCameraPreview` while the preview runs does nothing. A `StartCameraPreview` while an earlier start still opens the camera releases the camera of that earlier start, which then ends without an error. What happens next depends on why the start failed: From 8fbb0c2c0352eb92b917d0c5d18d1c5f4af358a5 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 19:54:11 -0800 Subject: [PATCH 67/98] Docs review fixes: scope the Camera error rule to the Android connection wait, say that Android also ends a recording when the preview stops, clarify the Windows restart Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 00f59df7..8e4b54d5 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -551,7 +551,7 @@ A recording starts and ends as follows: - **The camera is released while a start waits.** On Android, iOS and Mac Catalyst, when the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. - **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. - **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. -- **Stopping the preview ends the recording.** On Windows, `StopCameraPreview` while a recording runs ends the recording, and a later `StopVideoRecording` returns `Stream.Null`. +- **Stopping the preview ends the recording.** On Android and Windows, `StopCameraPreview` while a recording runs ends the recording. On Android, a later `StopVideoRecording` returns the video recorded until the stop, or throws a `CameraException` when nothing playable was recorded. On Windows, it returns `Stream.Null`. - **A failure to restore the camera after saving.** On Android, the camera switches to a video session for the recording and back to the photo session afterwards. When that switch back fails after the video was written, `StopVideoRecording` still returns the video, and the failure is reported through the `ErrorOccurred` event. The following example demonstrates how to use the `StartVideoRecording` method: @@ -702,15 +702,15 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, the exception of the camera connection that it waited for and that failed (see below). +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, the failure of the camera connection that it waited for (see below). ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); ``` -Each failure raises `ErrorOccurred` once. On Android, when the camera connection that a `StartCameraPreview` waited for fails, the connection raises `ErrorOccurred`, and `StartCameraPreview` throws the same exception to its caller instead of raising the event a second time. +Each failure raises `ErrorOccurred` once. On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection. When the connection fails, it raises `ErrorOccurred`, and the `StartCameraPreview` that waited throws the same failure to its caller instead of raising `ErrorOccurred` a second time. `StartCameraPreviewCommand` doesn't report that failure again. -On Windows, a `StartCameraPreview` while the preview runs does nothing. A `StartCameraPreview` while an earlier start still opens the camera releases the camera of that earlier start, which then ends without an error. +On Windows, a `StartCameraPreview` while the preview runs does nothing. A `StartCameraPreview` while an earlier start is still opening the camera releases the camera of that earlier start, which ends without reporting an error. What happens next depends on why the start failed: From ab37c337850ec951733fa6ed47abae0c09eff53c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 21:06:12 -0800 Subject: [PATCH 68/98] Docs: drop Tizen from the supported versions, add the MediaElement Android 8.0 (API 26) minimum, fix the TextColorTo argument and the repeated Start preview paragraph Co-Authored-By: Claude Opus 5.5 --- docs/maui/extensions/color-animation-extensions.md | 2 +- docs/maui/index.md | 3 +-- docs/maui/views/camera-view.md | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/maui/extensions/color-animation-extensions.md b/docs/maui/extensions/color-animation-extensions.md index 49a6809f..e4796506 100644 --- a/docs/maui/extensions/color-animation-extensions.md +++ b/docs/maui/extensions/color-animation-extensions.md @@ -58,7 +58,7 @@ await label.TextColorTo(Colors.Red); The full argument list for the `TextColorTo` method is: -- `color`, of type `Color`, is the target color to animate the `VisualElement`'s `BackgroundColor` to. +- `color`, of type `Color`, is the target color to animate the element's `TextColor` to. - `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. diff --git a/docs/maui/index.md b/docs/maui/index.md index 86eaed5f..4197f7c1 100644 --- a/docs/maui/index.md +++ b/docs/maui/index.md @@ -21,11 +21,10 @@ Feel free to browse the documentation using the table of contents on the left si The .NET MAUI Community Toolkit supports the platforms officially supported by [Microsoft](/dotnet/maui/supported-platforms): -* Android 5.0 (API 21) or higher. +* Android 5.0 (API 21) or higher. [MediaElement](views/MediaElement.md) requires Android 8.0 (API 26) or higher. * iOS 15.0 or higher is required. * macOS 12.0 or higher, using Mac Catalyst (15.0). * Windows 11 and Windows 10 version 1809 or higher, using [Windows UI Library (WinUI) 3](/windows/apps/winui/winui3/). -* Tizen 7.0 or higher. ## [Get started][get-started] diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 8e4b54d5..1fe4550e 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -708,7 +708,7 @@ A preview that can't start doesn't throw an exception. `StartCameraPreview` and Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); ``` -Each failure raises `ErrorOccurred` once. On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection. When the connection fails, it raises `ErrorOccurred`, and the `StartCameraPreview` that waited throws the same failure to its caller instead of raising `ErrorOccurred` a second time. `StartCameraPreviewCommand` doesn't report that failure again. +Each failure raises `ErrorOccurred` once. On Android, when the connection that such a `StartCameraPreview` waited for fails, the connection raises `ErrorOccurred`, and the `StartCameraPreview` throws the same failure to its caller instead of raising `ErrorOccurred` a second time. `StartCameraPreviewCommand` doesn't report that failure again. On Windows, a `StartCameraPreview` while the preview runs does nothing. A `StartCameraPreview` while an earlier start is still opening the camera releases the camera of that earlier start, which ends without reporting an error. From 416adbd0fe1979ae6ac78db7e6ef0d73c6f6442c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Thu, 5 Nov 2026 23:57:06 -0800 Subject: [PATCH 69/98] Docs: align the Camera statements with the final camera code (waiting start, turn-off after a recording, stop-preview result on iOS and Mac Catalyst), state the MediaElement Android minimum on its page, document the ColorTo token, update index.md ms.date Co-Authored-By: Claude Opus 5.5 --- docs/maui/extensions/color-animation-extensions.md | 2 ++ docs/maui/index.md | 2 +- docs/maui/views/MediaElement.md | 2 +- docs/maui/views/camera-view.md | 8 ++++---- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/maui/extensions/color-animation-extensions.md b/docs/maui/extensions/color-animation-extensions.md index e4796506..4682e4df 100644 --- a/docs/maui/extensions/color-animation-extensions.md +++ b/docs/maui/extensions/color-animation-extensions.md @@ -40,6 +40,7 @@ The full argument list for the `BackgroundColorTo` method is: - `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. +- `token`, of type `CancellationToken`, stops the wait for the animation: a cancelled token makes the call throw an `OperationCanceledException`, while the animation itself continues. This is an optional argument, whose default value is `default`. ## TextColorTo @@ -62,6 +63,7 @@ The full argument list for the `TextColorTo` method is: - `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. +- `token`, of type `CancellationToken`, stops the wait for the animation: a cancelled token makes the call throw an `OperationCanceledException`, while the animation itself continues. This is an optional argument, whose default value is `default`. > [!NOTE] > The `TextColorTo` method is generated at compilation time through the use of Source Generators. This is due to the fact that `ITextStyle.TextColor` is readonly. diff --git a/docs/maui/index.md b/docs/maui/index.md index 4197f7c1..d4b43f55 100644 --- a/docs/maui/index.md +++ b/docs/maui/index.md @@ -2,7 +2,7 @@ title: .NET MAUI Community Toolkit documentation author: bijington description: The .NET MAUI Community Toolkit is a collection of reusable elements for application development with .NET MAUI, including animations, behaviors, converters, effects, and helpers. -ms.date: 01/14/2022 +ms.date: 11/05/2026 --- # .NET Multi-platform App UI (.NET MAUI) Community Toolkit documentation diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index f2509e86..a3f692cf 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -20,7 +20,7 @@ ms.date: 11/05/2026 ![Screenshot of a MediaElement playing a video, on Android and iOS.](../../images/mediaelement/intro.png#lightbox) > [!NOTE] -> `MediaElement` is available on iOS, Android, Windows, macOS, and Tizen. +> `MediaElement` is available on iOS, Android 8.0 (API 26) or higher, Windows, macOS, and Tizen. The `MediaElement` uses the following platform implementations. diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 1fe4550e..09311a74 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -549,9 +549,9 @@ A recording starts and ends as follows: - **A second start joins the first.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. - **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`. On Android, iOS and Mac Catalyst, the recording that ran before ends and its video is discarded. Earlier versions on Android ignored the second start and kept the first recording. - **The camera is released while a start waits.** On Android, iOS and Mac Catalyst, when the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. -- **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. +- **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. When the recording ends, the camera turns off again and the preview stays stopped, unless your app started the preview. On iOS and Mac Catalyst, a `StartVideoRecording` that can't turn the camera on throws the failure. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. - **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. -- **Stopping the preview ends the recording.** On Android and Windows, `StopCameraPreview` while a recording runs ends the recording. On Android, a later `StopVideoRecording` returns the video recorded until the stop, or throws a `CameraException` when nothing playable was recorded. On Windows, it returns `Stream.Null`. +- **Stopping the preview ends the recording.** `StopCameraPreview` while a recording runs ends the recording. On Android, iOS and Mac Catalyst, a later `StopVideoRecording` returns the video recorded until the stop, or throws a `CameraException` when nothing playable was recorded. On Windows, it returns `Stream.Null`. - **A failure to restore the camera after saving.** On Android, the camera switches to a video session for the recording and back to the photo session afterwards. When that switch back fails after the video was written, `StopVideoRecording` still returns the video, and the failure is reported through the `ErrorOccurred` event. The following example demonstrates how to use the `StartVideoRecording` method: @@ -702,13 +702,13 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, the failure of the camera connection that it waited for (see below). +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, its own failure when it waited for a camera connection that failed (see below). ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); ``` -Each failure raises `ErrorOccurred` once. On Android, when the connection that such a `StartCameraPreview` waited for fails, the connection raises `ErrorOccurred`, and the `StartCameraPreview` throws the same failure to its caller instead of raising `ErrorOccurred` a second time. `StartCameraPreviewCommand` doesn't report that failure again. +Each failure raises `ErrorOccurred` once. On Android, when the camera connection that a `StartCameraPreview` waited for fails, `ErrorOccurred` reports that failure. If the `StartCameraPreview` then fails as well, for example because the camera permission isn't granted, it throws the exception to its caller instead of raising `ErrorOccurred` a second time. `StartCameraPreviewCommand` doesn't report that failure again. On Windows, a `StartCameraPreview` while the preview runs does nothing. A `StartCameraPreview` while an earlier start is still opening the camera releases the camera of that earlier start, which ends without reporting an error. From 3693c9fe189e2614e70c719d2993e4ed9b8beae0 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 00:06:34 -0800 Subject: [PATCH 70/98] Docs: apply the Opus review findings (SeekTo per platform, ColorTo token, ErrorOccurred restore wording, StartCameraPreview Android failure) Co-Authored-By: Claude Opus 5.5 --- docs/maui/extensions/color-animation-extensions.md | 4 ++-- docs/maui/views/MediaElement.md | 2 +- docs/maui/views/camera-view.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/maui/extensions/color-animation-extensions.md b/docs/maui/extensions/color-animation-extensions.md index 4682e4df..384d8f42 100644 --- a/docs/maui/extensions/color-animation-extensions.md +++ b/docs/maui/extensions/color-animation-extensions.md @@ -40,7 +40,7 @@ The full argument list for the `BackgroundColorTo` method is: - `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. -- `token`, of type `CancellationToken`, stops the wait for the animation: a cancelled token makes the call throw an `OperationCanceledException`, while the animation itself continues. This is an optional argument, whose default value is `default`. +- `token`, of type `CancellationToken`, ends the wait for the animation. With a token that is already cancelled, the call throws an `OperationCanceledException` and starts no animation. When the token is cancelled during the animation, the returned task throws an `OperationCanceledException`, and the animation runs to its end. This is an optional argument, whose default value is `default`. ## TextColorTo @@ -63,7 +63,7 @@ The full argument list for the `TextColorTo` method is: - `rate`, of type `uint`, is the time, in milliseconds, between the frames of the animation. This is an optional argument, whose default value is 16. It must be greater than 0: a `rate` of 0 throws an `ArgumentOutOfRangeException` from the call. - `length`, of type `uint`, is the duration, in milliseconds, of the animation. This is an optional argument, whose default value is 250. - `easing`, of type `Easing`, is the easing function to be used in the animation. This is an optional argument, whose default value is `null`. -- `token`, of type `CancellationToken`, stops the wait for the animation: a cancelled token makes the call throw an `OperationCanceledException`, while the animation itself continues. This is an optional argument, whose default value is `default`. +- `token`, of type `CancellationToken`, ends the wait for the animation. With a token that is already cancelled, the call throws an `OperationCanceledException` and starts no animation. When the token is cancelled during the animation, the returned task throws an `OperationCanceledException`, and the animation runs to its end. This is an optional argument, whose default value is `default`. > [!NOTE] > The `TextColorTo` method is generated at compilation time through the use of Source Generators. This is due to the fact that `ITextStyle.TextColor` is readonly. diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index a3f692cf..a44ae00c 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -484,7 +484,7 @@ For more information about using a [`Slider`](xref:Microsoft.Maui.Controls.Slide | Play | Starts playing the loaded media. On Android, iOS and Mac Catalyst, media that played to its end starts again from its start. | | Pause | Pauses playback of the current media. | | Stop | Stops playback and resets the position of the current media. | -| SeekTo | Takes a `TimeSpan` value to set the `Position` property to and takes a `CancellationToken` to cancel the `Task`. A position outside of the media is clamped to it: a position before the start seeks to the start, and a position beyond `Duration` seeks to the end. The seek then completes and raises `SeekCompleted` like any other. It throws an `InvalidOperationException` when the platform player can't seek yet, for example before it is ready. | +| SeekTo | Takes a `TimeSpan` value to set the `Position` property to and takes a `CancellationToken` to cancel the `Task`. A position outside of the media is clamped to it: a position before the start seeks to the start, and a position beyond `Duration` seeks to the end. The seek then completes and raises `SeekCompleted` like any other. On iOS and Mac Catalyst, it throws an `InvalidOperationException` while the media isn't ready to play yet. On Windows, a `SeekTo` while no media is loaded, or while the loaded media can't seek, seeks nothing: its task completes, and `SeekCompleted` isn't raised. | ## Examples diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 09311a74..e48601db 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -702,7 +702,7 @@ async void HandleStartCameraPreviewButtonTapped(object? sender, EventArgs e) On Android, a `StartCameraPreview` that you call while the `CameraView` is still connecting to its camera waits for the connection, then starts the preview. -A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, its own failure when it waited for a camera connection that failed (see below). +A preview that can't start doesn't throw an exception. `StartCameraPreview` and `StartCameraPreviewCommand` report it through the `ErrorOccurred` event on every platform. This includes a device without a camera, a camera permission that isn't granted, and a selected camera that can't be opened, for example because another app is using it. `StartCameraPreview` throws only an `OperationCanceledException` when the start is cancelled, an `InvalidOperationException` when the `CameraView` has no handler, for example before it is shown or after its handler was disconnected, and, on Android, the exception of a start that waited for a camera connection that failed and then failed as well (see below). ```cs Camera.ErrorOccurred += (sender, e) => Trace.WriteLine(e.Exception); @@ -853,7 +853,7 @@ The commands let no exception escape. `ICommand.Execute` can't return the task o |---------|---------|---------| | `MediaCaptured` | `EventHandler` | Raised when an image is successfully captured. The `MediaCapturedEventArgs` contains a `Media` property of type `Stream` with the captured image data. | | `MediaCaptureFailed` | `EventHandler` | Raised when an image capture fails, and when `StartVideoRecordingCommand` or `StopVideoRecordingCommand` fails. The `MediaCaptureFailedEventArgs` contains a `FailureReason` property with the error message. | -| `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. Each failure is reported once. On Android, it is also raised when the camera can't switch back to the photo session after `StopVideoRecording` has exported the video. | +| `ErrorOccurred` | `EventHandler` | Raised when the camera reports an error that no caller can catch, or a failure that `StartCameraPreview` reports instead of throwing. This covers connecting the camera when the `CameraView` is shown, switching to the camera in `SelectedCamera`, applying `ImageCaptureResolution`, a preview that can't start, the automatic start on Android once the camera permission is granted and, on Windows, updating `IsAvailable`. The `ErrorOccurredEventArgs` contains an `Exception` property with the exception. A start that `StopCameraPreview` cancels isn't an error and isn't reported. Each failure is reported once. On Android, it is also raised when the camera can't switch back to the photo session at the end of `StopVideoRecording`, whether or not the video could be saved. | ## Methods From 2d049514877ff15fa79a0d194cad8a0f5e553b00 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 02:49:29 -0800 Subject: [PATCH 71/98] Docs: state the Toast and Snackbar Windows wait for the notification listing, and that the Popup task completes after the navigation Co-Authored-By: Claude Opus 5.5 --- docs/maui/alerts/snackbar.md | 2 +- docs/maui/alerts/toast.md | 2 +- docs/maui/views/Popup.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/alerts/snackbar.md b/docs/maui/alerts/snackbar.md index 442f6d37..e06480c5 100644 --- a/docs/maui/alerts/snackbar.md +++ b/docs/maui/alerts/snackbar.md @@ -122,7 +122,7 @@ The `SnackbarOptions` allows you to customize the default `Snackbar` style. > [!NOTE] > You can display only 1 `Snackbar` at the same time. If you call the `Show` method a second time, the first `Snackbar` will automatically be dismissed before the second `Snackbar` is shown. -On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called, and the `Shown` and `Dismissed` events are raised in that order. A `Snackbar` that a later call replaced or dismissed doesn't stay on screen. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Snackbar` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Snackbar`: the other notifications that your app shows, for example those of a `Toast`, stay. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called, and the `Shown` and `Dismissed` events are raised in that order. A `Snackbar` that a later call replaced or dismissed doesn't stay on screen. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Snackbar` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Snackbar`: the other notifications that your app shows, for example those of a `Toast`, stay. The `Task` that `Show` returns completes once Windows lists the notification, or after at most 1 second, for example when notifications are turned off for your app. A `Snackbar` whose `Duration` is zero or less doesn't wait. > [!WARNING] > On Windows, a `Show` or `Dismiss` that you call from a `Shown` or `Dismissed` handler runs after the `Show` or `Dismiss` call that raised the event has finished. Await it. Blocking on its `Task` inside the handler, for example with `.Wait()` or `.Result`, deadlocks. diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index 793b4dae..47cd4815 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -77,7 +77,7 @@ These values adhere to the constants defined in the [`android.widget.Toast` API] > [!NOTE] > You can display only one `Toast` at a time. If you call the `Show` method a second time, the first `Toast` will automatically be dismissed. -On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called: the `Toast` of the last `Show` is the one that is displayed, and a `Dismiss` after it leaves none. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Toast` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Toast`: the other notifications that your app shows, for example those of a `Snackbar`, stay. +On Windows, overlapping `Show` and `Dismiss` calls take effect in the order in which they are called: the `Toast` of the last `Show` is the one that is displayed, and a `Dismiss` after it leaves none. The `Task` that `Show` or `Dismiss` returns completes after the earlier calls that overlap it have finished. A call whose token is cancelled before it starts to remove the displayed `Toast` throws an `OperationCanceledException` and removes nothing. `Show` and `Dismiss` remove only the notification of their own `Toast`: the other notifications that your app shows, for example those of a `Snackbar`, stay. The `Task` that `Show` returns completes once Windows lists the notification, or after at most 1 second, for example when notifications are turned off for your app. ## Examples diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index 93714d21..54c81531 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -182,7 +182,7 @@ By default a user can tap outside of the `Popup` to dismiss it. This can be cont ### Navigation removes the Popup -A `Popup` is displayed on a modal page, so navigation can remove it without a call to `CloseAsync`. For example, Shell navigates to another route, other code calls `PopModalAsync`, or the `Page` of the `Window` is replaced. The task that `ShowPopupAsync` returned then completes with an `IPopupResult` whose `WasDismissedByTappingOutsideOfPopup` is `true`, like when the user dismisses the `Popup` by tapping outside of it, and `Closed` is raised once. Earlier versions left that task pending and never raised `Closed`. +A `Popup` is displayed on a modal page, so navigation can remove it without a call to `CloseAsync`. For example, Shell navigates to another route, other code calls `PopModalAsync`, or the `Page` of the `Window` is replaced. After .NET MAUI has removed the `Popup`, the task that `ShowPopupAsync` returned completes with an `IPopupResult` whose `WasDismissedByTappingOutsideOfPopup` is `true`, like when the user dismisses the `Popup` by tapping outside of it, and `Closed` is raised once. Earlier versions left that task pending and never raised `Closed`. ## Lifecycle behavior From b8150fdf8a4faffd2f17127c38a9b4c03b2ae8c9 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 07:37:46 -0800 Subject: [PATCH 72/98] Docs: Windows starts the camera for a StartVideoRecording on a stopped preview, and a second start joins the first Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index e48601db..fac1c00c 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -542,14 +542,14 @@ The following example shows how to add a `Button` into the application and setup > You must provide a clean stream in order to record the video. > [!NOTE] -> `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). +> `StartVideoRecording` throws a `CameraException` when the recording can't start, for example on iOS and Mac Catalyst when the camera permission isn't granted, or on Windows when the camera can't be opened. It throws an `OperationCanceledException` when its token is cancelled, or `StopCameraPreview` is called, before the recording started. See [Cancel pending starts](#cancel-pending-starts). A recording starts and ends as follows: -- **A second start joins the first.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. +- **A second start joins the first.** On Android, iOS, Mac Catalyst and Windows, a `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. - **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`. On Android, iOS and Mac Catalyst, the recording that ran before ends and its video is discarded. Earlier versions on Android ignored the second start and kept the first recording. - **The camera is released while a start waits.** On Android, iOS and Mac Catalyst, when the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. -- **The preview was stopped.** On Android, iOS and Mac Catalyst, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. When the recording ends, the camera turns off again and the preview stays stopped, unless your app started the preview. On iOS and Mac Catalyst, a `StartVideoRecording` that can't turn the camera on throws the failure. On Windows, a `StartVideoRecording` records nothing while the preview isn't running: call `StartCameraPreview` first. +- **The preview was stopped.** On Android, iOS, Mac Catalyst and Windows, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. The camera is off again once the recording ends (`StopVideoRecording` returns), unless your app started the preview: a preview that your app started keeps running, also when it calls `StartCameraPreview` while the recording runs. When the camera can't start, a preview that was stopped stays stopped. On iOS, Mac Catalyst and Windows, `StartVideoRecording` then throws the failure, for example a `CameraException` without a camera or when the camera can't be opened, and an `UnauthorizedAccessException` on Windows when the privacy settings block the camera. On Android, a `StartVideoRecording` without a camera returns without recording. - **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. - **Stopping the preview ends the recording.** `StopCameraPreview` while a recording runs ends the recording. On Android, iOS and Mac Catalyst, a later `StopVideoRecording` returns the video recorded until the stop, or throws a `CameraException` when nothing playable was recorded. On Windows, it returns `Stream.Null`. - **A failure to restore the camera after saving.** On Android, the camera switches to a video session for the recording and back to the photo session afterwards. When that switch back fails after the video was written, `StopVideoRecording` still returns the video, and the failure is reported through the `ErrorOccurred` event. @@ -816,7 +816,7 @@ void HandleStopCameraPreviewButtonTapped(object? sender, EventArgs e) - A camera switch, which is a change of `SelectedCamera`. - On Android, the restart of the preview for a new `ImageCaptureResolution`, and the automatic start that waits for the camera permission. -None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` or `StartVideoRecording` again. On Windows, `StartVideoRecording` doesn't start the preview: call `StartCameraPreview`. +None of these is reported as a failure. The preview stays stopped until you call `StartCameraPreview` or `StartVideoRecording` again. A caller that awaits a cancelled `StartCameraPreview` or `StartVideoRecording` gets an `OperationCanceledException`, as when its own token is cancelled. This happens, for example, when your app calls `StopCameraPreview` in `OnDisappearing`, or from a stop button, while the camera is still starting. The commands don't report it as an error. On iOS and Mac Catalyst, `StartCameraPreview` with a token that is already cancelled also throws an `OperationCanceledException`, and doesn't start the preview. On Windows, a `StartCameraPreview` that its own token cancels after the camera has opened stops the preview that it had shown, and releases the camera. From f2a171668e678bab6332692804dcba7452cc4017 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 07:37:54 -0800 Subject: [PATCH 73/98] Docs: a cancelled StopVideoRecording still stops the recording, and a start during a recording ends the first Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/camera-view.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index fac1c00c..81959243 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -547,10 +547,11 @@ The following example shows how to add a `Button` into the application and setup A recording starts and ends as follows: - **A second start joins the first.** On Android, iOS, Mac Catalyst and Windows, a `StartVideoRecording` that you call while an earlier one still waits for the platform to start the recording waits for that recording and returns when it has started. The stream of the second call receives no video. When the first start fails, the second call throws the same exception. -- **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`. On Android, iOS and Mac Catalyst, the recording that ran before ends and its video is discarded. Earlier versions on Android ignored the second start and kept the first recording. +- **A start after a started recording replaces it.** The video goes to the stream of the latest `StartVideoRecording`, and the recording that ran before ends and its video is discarded. On Windows, the camera stays on between the two recordings, and the stream of the recording that ended goes back to the length and the position it had when that recording started, because Media Foundation writes into the stream while it records. On Android, an earlier version ignored the second start and kept the first recording. On Windows, an earlier version prepared a second recording without ending the first. - **The camera is released while a start waits.** On Android, iOS and Mac Catalyst, when the handler of the `CameraView` is disconnected, for example because the page closed, a `StartVideoRecording` that still waits throws a `TaskCanceledException`. -- **The preview was stopped.** On Android, iOS, Mac Catalyst and Windows, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. The camera is off again once the recording ends (`StopVideoRecording` returns), unless your app started the preview: a preview that your app started keeps running, also when it calls `StartCameraPreview` while the recording runs. When the camera can't start, a preview that was stopped stays stopped. On iOS, Mac Catalyst and Windows, `StartVideoRecording` then throws the failure, for example a `CameraException` without a camera or when the camera can't be opened, and an `UnauthorizedAccessException` on Windows when the privacy settings block the camera. On Android, a `StartVideoRecording` without a camera returns without recording. -- **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A second `StopVideoRecording`, with no recording running, returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. +- **The preview was stopped.** On Android, iOS, Mac Catalyst and Windows, a `StartVideoRecording` after your app called `StopCameraPreview`, or before it called `StartCameraPreview`, starts the camera itself, and then the recording. The camera is off again once the recording ends (`StopVideoRecording` returns or throws; on Android, iOS and Mac Catalyst a `StopVideoRecording` whose token was cancelled before the video was copied leaves it on until the next `StopVideoRecording`), unless your app started the preview: a preview that your app started keeps running, also when it calls `StartCameraPreview` while the recording runs. When the camera can't start, a preview that was stopped stays stopped. On iOS, Mac Catalyst and Windows, `StartVideoRecording` then throws the failure, for example a `CameraException` without a camera or when the camera can't be opened, and an `UnauthorizedAccessException` on Windows when the privacy settings block the camera. On Android, a `StartVideoRecording` without a camera returns without recording. +- **Stopping returns the video.** `StopVideoRecording` returns the `Stream` that received the video. A further `StopVideoRecording` after the one that returned the video returns `Stream.Null`. On Android, iOS and Mac Catalyst it throws a `CameraException` when the platform reports a recording that has no playable video. +- **A cancelled token doesn't keep the recording running.** The token of `StopVideoRecording` only cancels waiting for the video, not the stop. A token that is already cancelled, or that is cancelled while the stop waits for the video, still stops the recording that runs, and `StopVideoRecording` throws an `OperationCanceledException` instead of returning the video. Call `StopVideoRecording` again, with a token that isn't cancelled, to get the video. On Android, iOS and Mac Catalyst, a camera that the recording turned on stays on until then; on Windows it turns off with the cancelled stop. On Android, iOS and Mac Catalyst, a token that is cancelled while the video is being copied into your stream loses the video: the stream holds part of it, and the next `StopVideoRecording` returns `Stream.Null`. A cancelled token while nothing records returns `Stream.Null`, unless a cancelled stop left a video for the next `StopVideoRecording`: then it throws an `OperationCanceledException` again and keeps the video. A token that is cancelled while a start, or an earlier stop, still waits for the platform throws without stopping anything: a start that waits goes on and records. `StopVideoRecordingCommand` ends without an event in every one of these cases. Everything else is the same on Android, iOS, Mac Catalyst and Windows. - **Stopping the preview ends the recording.** `StopCameraPreview` while a recording runs ends the recording. On Android, iOS and Mac Catalyst, a later `StopVideoRecording` returns the video recorded until the stop, or throws a `CameraException` when nothing playable was recorded. On Windows, it returns `Stream.Null`. - **A failure to restore the camera after saving.** On Android, the camera switches to a video session for the recording and back to the photo session afterwards. When that switch back fails after the video was written, `StopVideoRecording` still returns the video, and the failure is reported through the `ErrorOccurred` event. @@ -865,7 +866,7 @@ The commands let no exception escape. `ICommand.Execute` can't return the task o | `StartVideoRecording(CancellationToken)` | `Task` | Starts recording video to an internal `MemoryStream`. Throws a `CameraException` when the recording can't start, and an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | | `StartVideoRecording(Stream, CancellationToken)` | `Task` | Starts recording video to the provided `Stream`. Throws a `CameraException` when the recording can't start, and an `OperationCanceledException` when the token is cancelled, or `StopCameraPreview` is called, before the recording started. | | `StopCameraPreview()` | `void` | Stops displaying the camera preview, and cancels a start of the preview or of a recording that is still in progress. | -| `StopVideoRecording(CancellationToken)` | `Task` | Stops video recording and returns the `Stream` that received the video, or `Stream.Null` when no recording runs. On Android, iOS and Mac Catalyst, throws a `CameraException` when the recording failed without a usable video. A recording that the platform ended early returns the video recorded until then. | +| `StopVideoRecording(CancellationToken)` | `Task` | Stops video recording and returns the `Stream` that received the video, or `Stream.Null` when no recording runs. A cancelled token stops the recording that runs, then throws an `OperationCanceledException`; the next `StopVideoRecording` returns the video. On Android, iOS and Mac Catalyst, throws a `CameraException` when the recording failed without a usable video. A recording that the platform ended early returns the video recorded until then. | ## CameraInfo From 99111e8176d09f8f5c1818e75c1ce2b70bc1cdbb Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:30:39 -0800 Subject: [PATCH 74/98] Docs: Popup shown from OnDisappearing only waits for the Page extension methods; Gravatar empty source and requested size Co-Authored-By: Claude Opus 5.5 --- docs/maui/imagesources/GravatarImageSource.md | 12 ++++++------ docs/maui/views/Popup.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/maui/imagesources/GravatarImageSource.md b/docs/maui/imagesources/GravatarImageSource.md index 9f2ca0f0..bb32eea2 100644 --- a/docs/maui/imagesources/GravatarImageSource.md +++ b/docs/maui/imagesources/GravatarImageSource.md @@ -69,7 +69,7 @@ partial class MyPage : ContentPage |---|---|---| | CacheValidity | `TimeSpan` | The `CacheValidity` property, of type `TimeSpan`, specifies how long the image will be stored locally for. The default value of this property is 1 day. | | CachingEnabled | `bool` | The `CachingEnabled` property, of type `bool`, defines whether image caching is enabled. The default value of this property is `true`. | -| Email | `string?` | The `Email` property, of type `string?`, specifies the gravatar account email address. If unset, the Gravatar image is rendered. If set and not found on Gravatar, the `Image` property image will be rendered. As Gravatar requires, the address is trimmed and converted to lower case before it is hashed, so `" User@Example.com "` and `"user@example.com"` load the same image. The value of the property doesn't change. | +| Email | `string?` | The `Email` property, of type `string?`, specifies the gravatar account email address. If unset or empty, the source is empty (its `IsEmpty` property is `true`) and no image is rendered; an `AvatarView` shows its `Text` instead. If set and not found on Gravatar, the `Image` property image will be rendered. As Gravatar requires, the address is trimmed and converted to lower case before it is hashed, so `" User@Example.com "` and `"user@example.com"` load the same image. The value of the property doesn't change. | | Image | `DefaultImage` | The `Image` property, of type [`DefaultImage`](#set-default-image) is an enumeration that is used to specify the default image if the `email` is not found on Gravatar. | These properties are backed by `BindableProperty` objects, which means that they can be targets of data bindings and styled. @@ -128,7 +128,7 @@ Image myImage = new() ## Set email -The `Email` property is a nullable `string`. If the property is null or empty, the default Gravatar image is rendered. If the email address has no matching Gravatar image, the `Image` property image is rendered. +The `Email` property is a nullable `string`. If the property is null or empty, the source is empty and no image is rendered. If the email address has no matching Gravatar image, the `Image` property image is rendered. The following example sets an email address that has a matching Gravatar image: @@ -152,7 +152,7 @@ Image myImage = new() }; ``` -The following example does not set an email address and will thus display the default Gravatar image. +The following example does not set an email address, so the source is empty and no image is rendered. ```xaml @@ -232,9 +232,9 @@ Image myImage = new() ## Set image size -By default, `GravatarImageSource` images are presented at 80px by 80px. Image sizes can be between *1px and 2048px* and are taken from their parent view size properties. Gravatar images are square, and the larger of the size properties defined will be taken. +By default, `GravatarImageSource` images are presented at 80px by 80px. Image sizes can be between *1px and 2048px* and are taken from their parent view size properties. Gravatar images are square, and the smaller of the width and the height of the image control is requested. -The following example sets the size of the image control and thus the size of the Gravatar image requested will be 73px. +The following example sets the size of the image control and thus the size of the Gravatar image requested will be 72px. ```xaml @@ -253,7 +253,7 @@ Image myImage = new() { Email = "dsiegel@avantipoint.com", }, - HeightRequest = 72, + WidthRequest = 72, HeightRequest = 73, }; ``` diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index 54c81531..f27a8631 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -232,7 +232,7 @@ protected override void OnNavigatedFrom(NavigatedFromEventArgs args) } ``` -When you show a `Popup` from `OnDisappearing` of a modal page that is being removed, for example after `PopModalAsync`, the `Popup` is displayed once the modal page has been removed, on the page below it. +When you call the `ShowPopup` or `ShowPopupAsync` extension method on a page, for example `this.ShowPopupAsync(popup)`, from `OnDisappearing` of a modal page that is being removed, for example after `PopModalAsync`, the `Popup` is displayed once the modal page has been removed, on the page below it. The overloads that take an `INavigation` or a `Shell`, and the methods of `IPopupService`, show the `Popup` at once, and .NET MAUI removes it again while it finishes removing the modal page. ## PopupOptions From ec487ffb7ea6b0a12521d7348809f8061dbdcf6c Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 02:50:02 -0800 Subject: [PATCH 75/98] Docs: remove the Tizen mentions from the pages whose packages ship no Tizen target Co-Authored-By: Claude Opus 5.5 --- docs/maui/alerts/toast.md | 1 - docs/maui/essentials/file-saver.md | 9 --------- docs/maui/essentials/folder-picker.md | 9 --------- docs/maui/includes/toast-snackbar-setup.md | 4 ---- docs/maui/views/MediaElement.md | 8 +------- docs/maui/views/camera-view.md | 4 ---- 6 files changed, 1 insertion(+), 34 deletions(-) diff --git a/docs/maui/alerts/toast.md b/docs/maui/alerts/toast.md index 47cd4815..3364abc1 100644 --- a/docs/maui/alerts/toast.md +++ b/docs/maui/alerts/toast.md @@ -91,4 +91,3 @@ You can find the source code for `Toast` over on the [.NET MAUI Community Toolki 1. The API allows override existing methods with your own implementation or creating your own Toast, by implementing `IToast` interface. 2. Toast is implemented on Android, created by Google. Other platforms use a custom-implemented container (`UIView` for iOS and MacCatalyst, `ToastNotification` on Windows). -3. Toast on Tizen can't be customized with its `Duration` and `TextSize` properties. diff --git a/docs/maui/essentials/file-saver.md b/docs/maui/essentials/file-saver.md index 53807f21..3681a06e 100644 --- a/docs/maui/essentials/file-saver.md +++ b/docs/maui/essentials/file-saver.md @@ -61,15 +61,6 @@ Further reading at [https://developer.apple.com/documentation/bundleresources/en Nothing is needed. -# [Tizen](#tab/tizen) - -Add permissions to `tizen-manifest.xml`: - -```xml -http://tizen.org/privilege/mediastorage -http://tizen.org/privilege/externalstorage -``` - --- ## Basic usage diff --git a/docs/maui/essentials/folder-picker.md b/docs/maui/essentials/folder-picker.md index 4186d73c..65d8887d 100644 --- a/docs/maui/essentials/folder-picker.md +++ b/docs/maui/essentials/folder-picker.md @@ -54,15 +54,6 @@ Further reading at: [https://developer.apple.com/documentation/bundleresources/e Nothing is needed. -# [Tizen](#tab/tizen) - -Add permissions to `tizen-manifest.xml`: - -```xml -http://tizen.org/privilege/mediastorage -http://tizen.org/privilege/externalstorage -``` - --- ## Basic usage diff --git a/docs/maui/includes/toast-snackbar-setup.md b/docs/maui/includes/toast-snackbar-setup.md index 049eefcf..1d2f7a86 100644 --- a/docs/maui/includes/toast-snackbar-setup.md +++ b/docs/maui/includes/toast-snackbar-setup.md @@ -192,9 +192,5 @@ Below is an example `Package.appxmanifest` file that has been updated to support For more information on handling activation: [Send a local toast notification from C# apps](/windows/apps/design/shell/tiles-and-notifications/send-local-toast?tabs=uwp#step-3-handling-activation) -### [Tizen](#tab/tizen) - -No setup is required. - ----- diff --git a/docs/maui/views/MediaElement.md b/docs/maui/views/MediaElement.md index a44ae00c..cfe3680b 100644 --- a/docs/maui/views/MediaElement.md +++ b/docs/maui/views/MediaElement.md @@ -20,7 +20,7 @@ ms.date: 11/05/2026 ![Screenshot of a MediaElement playing a video, on Android and iOS.](../../images/mediaelement/intro.png#lightbox) > [!NOTE] -> `MediaElement` is available on iOS, Android 8.0 (API 26) or higher, Windows, macOS, and Tizen. +> `MediaElement` is available on iOS, Android 8.0 (API 26) or higher, Windows, and macOS. The `MediaElement` uses the following platform implementations. @@ -112,11 +112,6 @@ Edit the `Info.plist` for `iOS` and add the following keys. No setup is required. - -### [Tizen](#tab/tizen) - -No setup is required. - ----- @@ -129,7 +124,6 @@ The supported multimedia formats can be different per platform. In some cases it | Android | [ExoPlayer Supported Formats](https://developer.android.com/guide/topics/media/exoplayer/supported-formats) | | | iOS/macOS | [iOS/macOS Supported Formats](https://stackoverflow.com/a/45898816/1506387) | No official documentation on this exists | | Windows | [Windows Supported Formats](/windows/uwp/audio-video-camera/supported-codecs) | On Windows the supported formats are very much dependent on what codecs are installed on the user's machine | -| Tizen | [Tizen Supported Formats](https://docs.tizen.org/application/native/tutorials/feature/app-multimedia-video) | | > [!IMPORTANT] > If the user is using a Windows N edition, no video playback is supported by default. Windows N editions have no video playback formats installed by design. diff --git a/docs/maui/views/camera-view.md b/docs/maui/views/camera-view.md index 81959243..b9e93dcd 100644 --- a/docs/maui/views/camera-view.md +++ b/docs/maui/views/camera-view.md @@ -163,10 +163,6 @@ More details can be found here: https://developer.apple.com/documentation/avfoun No setup is required. -### [Tizen](#tab/tizen) - -Tizen is not currently supported. - ----- From 6422b631fdef3060f7c7059d6e23d357fbb916bd Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 02:50:02 -0800 Subject: [PATCH 76/98] Docs: fix the three ../popup.md links to the real file name Popup.md Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/popup/popup-complex.md | 4 ++-- docs/maui/views/popup/popup-result.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/maui/views/popup/popup-complex.md b/docs/maui/views/popup/popup-complex.md index ecc971eb..fd417721 100644 --- a/docs/maui/views/popup/popup-complex.md +++ b/docs/maui/views/popup/popup-complex.md @@ -9,7 +9,7 @@ ms.date: 07/03/2025 This page makes use of the following features to provide a comprehensive example: -- [`Popup`](../popup.md) +- [`Popup`](../Popup.md) - [`IPopupService`](../popup-service.md) - [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup-options.md) - [`Popup` - Returning a result](./popup-result.md) @@ -272,7 +272,7 @@ You can find the source code for `Popup` over on the [.NET MAUI Community Toolki ## Additional Resources -- [`Popup`](../popup.md) +- [`Popup`](../Popup.md) - [`IPopupService`](../popup-service.md) - [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup-options.md) - [`Popup` - Returning a result](./popup-result.md) diff --git a/docs/maui/views/popup/popup-result.md b/docs/maui/views/popup/popup-result.md index c1076b06..b51a2606 100644 --- a/docs/maui/views/popup/popup-result.md +++ b/docs/maui/views/popup/popup-result.md @@ -175,7 +175,7 @@ You can find the source code for `Popup` over on the [.NET MAUI Community Toolki ## Additional Resources -- [`Popup`](../popup.md) +- [`Popup`](../Popup.md) - [`IPopupService`](../popup-service.md) - [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup-options.md) - [`Popup` - Combining Popup features to provide a comprehensive example](./popup-complex.md) From 8a02840b8114f015b24d726fd5e1118dfa99d1f8 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 17:47:34 -0800 Subject: [PATCH 77/98] Docs: GravatarImageSource cancellation note and Popup calls that throw OperationCanceledException when the app cancels the navigation Co-Authored-By: Claude Opus 5.5 --- docs/maui/imagesources/GravatarImageSource.md | 7 +++++++ docs/maui/views/Popup.md | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/docs/maui/imagesources/GravatarImageSource.md b/docs/maui/imagesources/GravatarImageSource.md index bb32eea2..ac4ca0d0 100644 --- a/docs/maui/imagesources/GravatarImageSource.md +++ b/docs/maui/imagesources/GravatarImageSource.md @@ -258,6 +258,13 @@ Image myImage = new() }; ``` +## Cancellation + +> [!NOTE] +> `IStreamImageSource.GetStreamAsync(CancellationToken)` and the default `Stream` function throw an `OperationCanceledException` only when the `CancellationToken` passed to them is canceled, because one load of a `GravatarImageSource` never cancels another. +> A load that you start with `CancellationToken.None` never throws it, and .NET MAUI catches it for the loads that it cancels itself. +> `ImageSource.Cancel()` ends the loads that were started without a cancelable token, which then return `Stream.Null`. + ## Examples You can find examples of this control in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/ImageSources/GravatarImageSourcePage.xaml). diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md index f27a8631..1ed76e38 100644 --- a/docs/maui/views/Popup.md +++ b/docs/maui/views/Popup.md @@ -184,6 +184,13 @@ By default a user can tap outside of the `Popup` to dismiss it. This can be cont A `Popup` is displayed on a modal page, so navigation can remove it without a call to `CloseAsync`. For example, Shell navigates to another route, other code calls `PopModalAsync`, or the `Page` of the `Window` is replaced. After .NET MAUI has removed the `Popup`, the task that `ShowPopupAsync` returned completes with an `IPopupResult` whose `WasDismissedByTappingOutsideOfPopup` is `true`, like when the user dismisses the `Popup` by tapping outside of it, and `Closed` is raised once. Earlier versions left that task pending and never raised `Closed`. +### Navigation that the app cancels + +> [!NOTE] +> `ShowPopupAsync`, `CloseAsync` and `ClosePopupAsync` throw an `OperationCanceledException` when the app cancels the navigation that displays or removes the `Popup`, for example by calling `e.Cancel()` in a `Shell.Navigating` handler, or by setting `e.Cancel` to `true` in a `Window.ModalPopping` or `Application.ModalPopping` handler. The `Popup` is then not displayed, or stays open. Earlier versions left the call pending forever. +> +> A tap outside of the `Popup`, or the hardware back button on Android, that triggers a navigation the app cancels does not throw: the `Popup` stays open and a later tap or back press can close it. + ## Lifecycle behavior It is important to note that a `Popup` will be displayed inside `ContentPage` which is then shown modally in a .NET MAUI application. The impact of this will result in any calling `Page` to have the following lifecycle events to be called: From d1d3958c98aaf5415b32293d84a3690042913564 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Fri, 6 Nov 2026 19:50:35 -0800 Subject: [PATCH 78/98] Expander: Enter and Space toggle on release, like a Button Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Expander.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index af53bb77..b5332c2a 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -133,7 +133,7 @@ Keyboard and screen reader users can expand and collapse an `Expander` through i |Platform |Behavior | |---------|---------| -| Windows | The `Expander` is a Tab stop. Enter toggles it when it is pressed and Space when it is released, like a `Button`. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. The button is disabled while a tap can't toggle the `Expander`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | +| Windows | The `Expander` is a Tab stop. Enter and Space toggle it when they are released, like a `Button`, and pressing another key before the release cancels the toggle. The focus visual frames only the row of the `Header`. UI Automation exposes the `Expander` as a button with the class name `Expander`, and with the `ExpandCollapse` and `Invoke` patterns. Its name comes from the `Header`: the semantic description, the text, or the texts of the views a layout `Header` holds. Its help text comes from the `SemanticProperties.Hint` of the `Header`. The button is disabled while a tap can't toggle the `Expander`. It raises the `ExpandCollapseState` property changed event whenever `IsExpanded` changes, also when code changes it. | | Android | TalkBack announces the `Header` as collapsed or expanded, and lists the expand action in its actions menu while the `Expander` is collapsed, and the collapse action while it is expanded. A double tap with TalkBack still taps the `Header`, which toggles the `Expander`. | | iOS and Mac Catalyst | VoiceOver reads the whole `Header` as one button that a double tap toggles. The element has the button trait, the header trait when the `Header` is a heading, and the not enabled trait while a tap can't toggle the `Expander`. Its label, hint and `AutomationId` come from the `Header`. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A `Header` that holds a control, such as a `Button`, a `Switch` or an `Entry`, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the `Expander` for it. A `Header` with another `TapGestureRecognizer` lets VoiceOver tap it, so that every recognizer runs. | From ca19094fcae879039705383afe3cbbe859837673 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Sat, 7 Nov 2026 00:47:51 -0800 Subject: [PATCH 79/98] Expander: an app's LayoutHandler.PlatformViewFactory turns off the header's keyboard and screen reader support Co-Authored-By: Claude Opus 5.5 --- docs/maui/views/Expander.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maui/views/Expander.md b/docs/maui/views/Expander.md index b5332c2a..12a8ee56 100644 --- a/docs/maui/views/Expander.md +++ b/docs/maui/views/Expander.md @@ -142,7 +142,7 @@ Every activation from the keyboard or from assistive technology goes through the > [!IMPORTANT] > `HandleHeaderTapped` also runs when the `Header` is activated without a tap: from the keyboard or by UI Automation on Windows, by the expand or collapse action of TalkBack on Android, and by VoiceOver on iOS and Mac Catalyst. For these activations `TappedEventArgs.Parameter` is `null`, and `TappedEventArgs.GetPosition` returns the center of the `Header` on Windows and `null` on Android, iOS and Mac Catalyst. A custom `HandleHeaderTapped` that assumes a pointer position must handle `null`. -The `UseMauiCommunityToolkit` method registers a handler for the layout of the `Expander`, which provides this on Windows, iOS and Mac Catalyst. A handler that your app registers for `Grid` no longer applies to the `Grid` of the `Expander`. Changes to `LayoutHandler.Mapper` still apply. +The `UseMauiCommunityToolkit` method registers a handler for the layout of the `Expander`, which provides this on Windows, iOS and Mac Catalyst. A handler that your app registers for `Grid` no longer applies to the `Grid` of the `Expander`. Changes to `LayoutHandler.Mapper` still apply. If your app sets `LayoutHandler.PlatformViewFactory`, that factory also creates the platform view of the layout of the `Expander`, which then has no keyboard or UI Automation support on Windows, and VoiceOver doesn't read its `Header` as one button on iOS and Mac Catalyst. ### UI tests From b605b2a68f874eb9de6bdacf1cafb4f53cd7cee7 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Sat, 7 Nov 2026 08:49:19 -0800 Subject: [PATCH 80/98] Docs: remove the Tizen tabs, platform mention and EnumToBoolConverter sample value for the .NET 11 release Co-Authored-By: Claude Opus 5.5 --- docs/maui/converters/enum-to-bool-converter.md | 15 +++++++-------- docs/maui/essentials/badge.md | 10 +--------- docs/maui/essentials/index.md | 4 ++-- docs/maui/essentials/speech-to-text.md | 10 +--------- 4 files changed, 11 insertions(+), 28 deletions(-) diff --git a/docs/maui/converters/enum-to-bool-converter.md b/docs/maui/converters/enum-to-bool-converter.md index 7d2b31e0..290e9f8b 100644 --- a/docs/maui/converters/enum-to-bool-converter.md +++ b/docs/maui/converters/enum-to-bool-converter.md @@ -2,7 +2,7 @@ title: EnumToBoolConverter - .NET MAUI Community Toolkit author: VladislavAntonyuk description: "The EnumToBoolConverter is a one way converter that allows you to convert an Enum to a corresponding bool based on whether it is equal to a set of supplied enum values." -ms.date: 05/04/2022 +ms.date: 11/10/2026 --- # EnumToBoolConverter @@ -34,7 +34,6 @@ public enum MyDevicePlatform Android, iOS, macOS, - Tizen, Windows } ``` @@ -91,8 +90,8 @@ It is also possible to pass the converter parameter: - ``` @@ -112,7 +111,7 @@ class EnumToBoolConverterPage : ContentPage var label = new Label { - Text = "I am visible when the Picker value is Tizen." + Text = "I am visible when the Picker value is Windows." }; label.SetBinding( @@ -120,7 +119,7 @@ class EnumToBoolConverterPage : ContentPage new Binding( static (ViewModel vm) => vm.SelectedPlatform, converter: new EnumToBoolConverter(), - converterParameter: MyDevicePlatform.Tizen)); + converterParameter: MyDevicePlatform.Windows)); Content = new VerticalStackLayout { @@ -154,12 +153,12 @@ class EnumToBoolConverterPage : ContentPage static (ViewModel vm) => vm.SelectedPlatform), new Label() - .Text("I am visible when the Picker value is Tizen.") + .Text("I am visible when the Picker value is Windows.") .Bind( Label.IsVisibleProperty, static (ViewModel vm) => vm.SelectedPlatform, converter: new EnumToBoolConverter(), - converterParameter: MyDevicePlatform.Tizen) + converterParameter: MyDevicePlatform.Windows) } }; } diff --git a/docs/maui/essentials/badge.md b/docs/maui/essentials/badge.md index e255fbdb..d091460c 100644 --- a/docs/maui/essentials/badge.md +++ b/docs/maui/essentials/badge.md @@ -2,7 +2,7 @@ title: Badge - .NET MAUI Community Toolkit author: VladislavAntonyuk description: The Badge API allows developers to set the app icon badge number on the home screen. -ms.date: 11/05/2026 +ms.date: 11/10/2026 --- # Badge @@ -26,14 +26,6 @@ Authorize Badge permission for the app. It is automatically requested. Windows shows a badge only for an app with package identity, which is a packaged app. An unpackaged app, which is the default of the .NET MAUI template (`None`), doesn't show a badge: `SetCount` writes a line to the trace output and does nothing else. To show a badge, package the app by setting `WindowsPackageType` to `MSIX` in the project file. -# [Tizen](#tab/tizen) - -Add permissions to `tizen-manifest.xml`: - -```xml -http://tizen.org/privilege/notification -``` - --- ## Syntax diff --git a/docs/maui/essentials/index.md b/docs/maui/essentials/index.md index 2bf47c77..b0cfac0b 100644 --- a/docs/maui/essentials/index.md +++ b/docs/maui/essentials/index.md @@ -2,12 +2,12 @@ title: Essentials - .NET MAUI Community Toolkit author: jfversluis description: The .NET MAUI Community Toolkit Essentials provides developers with cross-platform APIs for their applications. -ms.date: 08/09/2023 +ms.date: 11/10/2026 --- # Essentials -Android, iOS, MacCatalyst, Windows, and Tizen offer unique operating system and platform APIs that developers have access to all in C# leveraging .NET. Essentials provides a single cross-platform API that works with any .NET MAUI application that can be accessed from shared code no matter how the user interface is created. +Android, iOS, MacCatalyst, and Windows offer unique operating system and platform APIs that developers have access to all in C# leveraging .NET. Essentials provides a single cross-platform API that works with any .NET MAUI application that can be accessed from shared code no matter how the user interface is created. ## .NET MAUI Community Toolkit Essentials diff --git a/docs/maui/essentials/speech-to-text.md b/docs/maui/essentials/speech-to-text.md index b0b629cc..ea3c9821 100644 --- a/docs/maui/essentials/speech-to-text.md +++ b/docs/maui/essentials/speech-to-text.md @@ -2,7 +2,7 @@ title: SpeechToText - .NET MAUI Community Toolkit author: VladislavAntonyuk description: The SpeechToText provides the ability to convert speech to text. -ms.date: 05/26/2023 +ms.date: 11/10/2026 --- # SpeechToText @@ -45,14 +45,6 @@ Add permissions to `Package.appxmanifest` ``` -# [Tizen](#tab/tizen) - -Add permissions to `tizen-manifest.xml`: - -```xml -http://tizen.org/feature/microphone -``` - --- ## Basic usage From 77917758e693bc2259a64b294ebdf09db2d7a193 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Sat, 7 Nov 2026 08:49:48 -0800 Subject: [PATCH 81/98] Docs: Maps package removed in the .NET 11 release, with the migration to .NET MAUI Map; .NET 11 supported versions Co-Authored-By: Claude Opus 5.5 --- docs/maui/TOC.yml | 2 +- docs/maui/get-started.md | 57 ++------------------------------ docs/maui/index.md | 12 ++++--- docs/maui/views/Map.md | 70 ++++++++++++++++------------------------ docs/maui/views/index.md | 4 +-- 5 files changed, 40 insertions(+), 105 deletions(-) diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml index 412a1689..c361797b 100644 --- a/docs/maui/TOC.yml +++ b/docs/maui/TOC.yml @@ -233,7 +233,7 @@ items: href: views/Expander.md - name: "LazyView" href: views/LazyView.md - - name: "Map (Windows) (Deprecated)" + - name: "Map (Removed)" href: views/Map.md - name: "MediaElement" href: views/MediaElement.md diff --git a/docs/maui/get-started.md b/docs/maui/get-started.md index 7f1543ce..3c7b6ba3 100644 --- a/docs/maui/get-started.md +++ b/docs/maui/get-started.md @@ -2,7 +2,7 @@ title: Getting Started with the .NET Multi-platform App UI (.NET MAUI) Community Toolkit author: bijington description: The toolkit is available as a set of NuGet packages that can be added to any existing or new .NET MAUI project. -ms.date: 11/05/2026 +ms.date: 11/10/2026 --- # Getting Started with the .NET Multi-platform App UI (.NET MAUI) Community Toolkit @@ -77,61 +77,10 @@ To use the features of the toolkit please refer to the documentation pages for e ### [Maps](#tab/CommunityToolkitMauiMaps) -This package enables you to display a map in your .NET MAUI Windows application. +The `CommunityToolkit.Maui.Maps` package is removed. > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. On Windows, it uses the WinUI 3 `MapControl`, which is backed by Azure Maps. -> -> To move to it, remove the `CommunityToolkit.Maui.Maps` package and make sure your project references the `Microsoft.Maui.Controls.Maps` package directly, because `CommunityToolkit.Maui.Maps` referenced it for you. Remove `using CommunityToolkit.Maui.Maps;` and the call to `UseMauiCommunityToolkitMaps`, and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"))`. Without a valid key, the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). -> -> On Windows, the .NET MAUI `Map` doesn't support: -> -> - `IsShowingUser` -> - Polygons, polylines and circles in `MapElements` -> - Pin labels and info windows -> - The `MapClicked` event -> -> It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. -> -> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). - -**Package name:** `CommunityToolkit.Maui.Maps` - -**Package url:** https://www.nuget.org/packages/CommunityToolkit.Maui.Maps - -#### Initializing the package - -First the using statement needs to be added to the top of your *MauiProgram.cs* file - -```csharp -using CommunityToolkit.Maui.Maps; -``` - -In order to use the `Map` correctly the `.UseMauiCommunityToolkitMaps` method must be called on the `MauiAppBuilder` class when bootstrapping an application the *MauiProgram.cs* file. This method expects a valid Bing Maps API key which you can obtain through the [Bing Maps Portal](https://www.bingmapsportal.com/). - -The following example shows how to perform this. - -```csharp -var builder = MauiApp.CreateBuilder(); -builder - .UseMauiApp() - .UseMauiCommunityToolkitMaps("YOUR_API_KEY") -``` - -When using the .NET MAUI Community Toolkit Map for Windows and the regular .NET MAUI Maps together, you will need to make sure that each initialization call is only made for the relevant platform. The following example shows how to do this. - -```csharp -var builder = MauiApp.CreateBuilder(); -builder - .UseMauiApp() -#if ANDROID || IOS - .UseMauiMaps() -#elif WINDOWS - .UseMauiCommunityToolkitMaps("YOUR_API_KEY") -#endif -``` - -For more information on how to initialize the map on iOS and Android, as well as how to work with the map control API, see the [.NET MAUI Maps documentation](/dotnet/maui/user-interface/controls/map). +> `CommunityToolkit.Maui.Maps` was deprecated in the previous release and is removed in the .NET 11 release. The package has no .NET 11 version. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package instead. For the steps to move to it, see [Map](views/Map.md). ### [MediaElement](#tab/CommunityToolkitMauiMediaElement) diff --git a/docs/maui/index.md b/docs/maui/index.md index d4b43f55..f9531244 100644 --- a/docs/maui/index.md +++ b/docs/maui/index.md @@ -2,7 +2,7 @@ title: .NET MAUI Community Toolkit documentation author: bijington description: The .NET MAUI Community Toolkit is a collection of reusable elements for application development with .NET MAUI, including animations, behaviors, converters, effects, and helpers. -ms.date: 11/05/2026 +ms.date: 11/10/2026 --- # .NET Multi-platform App UI (.NET MAUI) Community Toolkit documentation @@ -21,10 +21,12 @@ Feel free to browse the documentation using the table of contents on the left si The .NET MAUI Community Toolkit supports the platforms officially supported by [Microsoft](/dotnet/maui/supported-platforms): -* Android 5.0 (API 21) or higher. [MediaElement](views/MediaElement.md) requires Android 8.0 (API 26) or higher. -* iOS 15.0 or higher is required. -* macOS 12.0 or higher, using Mac Catalyst (15.0). -* Windows 11 and Windows 10 version 1809 or higher, using [Windows UI Library (WinUI) 3](/windows/apps/winui/winui3/). +* Android 7.0 (API 24) or higher. [MediaElement](views/MediaElement.md) requires Android 8.0 (API 26) or higher. +* iOS 15.0 or higher. +* macOS 14 or higher, using Mac Catalyst 17.0. +* Windows 10 version 1809 (10.0.17763) or higher, using [Windows UI Library (WinUI) 3](/windows/apps/winui/winui3/). + +These versions match the minimum versions of .NET MAUI 11. ## [Get started][get-started] diff --git a/docs/maui/views/Map.md b/docs/maui/views/Map.md index 4bb76035..acdb5554 100644 --- a/docs/maui/views/Map.md +++ b/docs/maui/views/Map.md @@ -1,59 +1,43 @@ --- -title: Map - .NET MAUI Community Toolkit +title: Map (Removed) - .NET MAUI Community Toolkit author: jfversluis -description: "The Map control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps." -ms.date: 11/05/2026 +description: "CommunityToolkit.Maui.Maps was removed in the .NET 11 release. Use the Map control from Microsoft.Maui.Controls.Maps instead." +ms.date: 11/10/2026 --- # Map -The `Map` control is a cross-platform view for displaying and annotating maps. The .NET MAUI Community Toolkit provides a Windows implementation that uses Bing Maps. - > [!WARNING] -> `CommunityToolkit.Maui.Maps` is deprecated and will be removed in a future release. Use .NET MAUI's own `Map` from the `Microsoft.Maui.Controls.Maps` package, which supports Windows starting with .NET MAUI 10. On Windows, it uses the WinUI 3 `MapControl`, which is backed by Azure Maps. -> -> To move to it, remove the `CommunityToolkit.Maui.Maps` package and make sure your project references the `Microsoft.Maui.Controls.Maps` package directly, because `CommunityToolkit.Maui.Maps` referenced it for you. Remove `using CommunityToolkit.Maui.Maps;` and the call to `UseMauiCommunityToolkitMaps`, and call `UseMauiMaps` on every platform. On Windows, set your Azure Maps subscription key with `builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY"))`. Without a valid key, the map shows no map data. For more information, see [Map](/dotnet/maui/user-interface/controls/map). -> -> On Windows, the .NET MAUI `Map` doesn't support: -> -> - `IsShowingUser` -> - Polygons, polylines and circles in `MapElements` -> - Pin labels and info windows -> - The `MapClicked` event -> -> It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. -> -> This library implements `Map` on Windows with Bing Maps for Enterprise, which Microsoft is retiring: free (Basic) accounts were retired on June 30, 2025, and Enterprise accounts can use it until June 30, 2028. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). - -## Setup - -Before you are able to use `Map` inside your application you will need to install the NuGet package and add an initialization line in your *MauiProgram.cs*. For more information on how to do this, please refer to the [Get Started](../get-started.md) page. - -## Usage - -The API of the .NET MAUI Community Toolkit implementation for Windows is not different from the API of the .NET MAUI Maps implementation for iOS and Android. - -For details on how to work with this map control, please refer to the [.NET MAUI Map documentation](/dotnet/maui/user-interface/controls/map). +> `CommunityToolkit.Maui.Maps` was deprecated in the previous release and is removed in the .NET 11 release. The package has no .NET 11 version. The `Map` control for Windows that it provided used Bing Maps for Enterprise, which Microsoft is retiring. For more information, see [Deprecate Map Control in favor of MAUI Map implementation](https://github.com/CommunityToolkit/Maui/issues/3190). -## Map types +.NET MAUI includes its own `Map` control in the `Microsoft.Maui.Controls.Maps` package. It supports Android, iOS, Mac Catalyst and Windows. On Windows, it uses the WinUI 3 `MapControl`, which is backed by Azure Maps. For details on how to work with the control, see the [.NET MAUI Map documentation](/dotnet/maui/user-interface/controls/map). -The `MapType` of the map decides what the Windows map shows, as it does on iOS and Android: +## Migrate to the .NET MAUI Map -|MapType |Windows shows | -|---------|---------| -| `Street` | The road map. | -| `Satellite` | Aerial imagery without place or road labels. | -| `Hybrid` | Aerial imagery with labels. | +1. Remove the `CommunityToolkit.Maui.Maps` package from your project. +1. Add the `Microsoft.Maui.Controls.Maps` package to your project. `CommunityToolkit.Maui.Maps` referenced it for you, so your project might not reference it directly yet. +1. Remove `using CommunityToolkit.Maui.Maps;` and the call to `UseMauiCommunityToolkitMaps` from *MauiProgram.cs*. +1. Call `UseMauiMaps` on the `MauiAppBuilder` for every platform. +1. On Windows, set your Azure Maps subscription key. Without a valid key, the map shows no map data. -A value outside of the `MapType` enumeration shows the road map. +```csharp +var builder = MauiApp.CreateBuilder(); +builder + .UseMauiApp() + .UseMauiMaps(); -> [!NOTE] -> Earlier versions showed the labels for `Satellite` too, so it looked the same as `Hybrid`. If your app chose `Satellite` on Windows to get labels, choose `Hybrid`. +#if WINDOWS +builder.ConfigureEssentials(essentials => essentials.UseMapServiceToken("YOUR_AZURE_MAPS_SUBSCRIPTION_KEY")); +#endif +``` -## Examples +## Windows limitations -You can find examples of this control in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/tree/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/Maps). +On Windows, the .NET MAUI `Map` doesn't support: -## API +- `IsShowingUser` +- Polygons, polylines and circles in `MapElements` +- Pin labels and info windows +- The `MapClicked` event -You can find the source code for `Map` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui.Maps/AppBuilderExtensions.shared.cs). +It supports `MoveToRegion`, the `Street`, `Satellite` and `Hybrid` map types, traffic, scrolling, zooming and pins. diff --git a/docs/maui/views/index.md b/docs/maui/views/index.md index b490838f..5fc69cf5 100644 --- a/docs/maui/views/index.md +++ b/docs/maui/views/index.md @@ -2,7 +2,7 @@ title: Views - .NET MAUI Community Toolkit author: jfversluis description: The .NET MAUI Community Toolkit extends .NET MAUI controls. -ms.date: 06/13/2023 +ms.date: 11/10/2026 --- # Views @@ -24,7 +24,7 @@ The .NET MAUI Community Toolkit provides a collection of pre-built, reusable vie | [`DrawingView`](DrawingView.md) | The `DrawingView` provides a surface that allows for the drawing of lines through the use of touch or mouse interaction. The result of a users drawing can be saved out as an image. | | [`Expander`](Expander.md) | The `Expander` control provides an expandable container to host any content. | | [`LazyView`](LazyView.md) | The `LazyView` control allows you to delay the initialization of a View.| -| [`Map (Windows)`](Map.md) | The `Map` control is a cross-platform view for displaying and annotating maps. The Windows implementation is available through the .NET MAUI Community Toolkit. | +| [`Map (Removed)`](Map.md) | The Windows `Map` implementation was removed in the .NET 11 release. Use the `Map` control from .NET MAUI instead. | | [`MediaElement`](MediaElement.md) | The `MediaElement` is a view for playing multimedia such as audio and video. | | [`Popup`](Popup.md) | The `Popup` view allows developers to build their own custom UI and present it to their users. | | [`RatingView`](RatingView.md) | The `RatingView` is an ItemTemplate designed to provide developers with a flexible and customizable rating mechanism, similar to those used on popular review and feedback platforms. | From ba70c52a5bd355ebffeb125c0af609b412ce7890 Mon Sep 17 00:00:00 2001 From: Brandon Minnick <13558917+TheCodeTraveler@users.noreply.github.com> Date: Sat, 7 Nov 2026 08:50:34 -0800 Subject: [PATCH 82/98] Docs: describe how the converters and EventToCommandBehavior use the culture in the .NET 11 release Co-Authored-By: Claude Opus 5.5 --- .../behaviors/event-to-command-behavior.md | 19 ++++++++++++++++++- .../color-to-cmyk-string-converter.md | 6 +++++- .../color-to-hsl-string-converter.md | 6 +++++- .../color-to-hsla-string-converter.md | 6 +++++- .../color-to-rgba-string-converter.md | 6 +++++- docs/maui/converters/compare-converter.md | 6 +++++- .../converters/datetimeoffsetconverter.md | 6 +++++- .../converters/double-to-int-converter.md | 6 +++++- docs/maui/converters/index.md | 14 +++++++++++++- docs/maui/converters/is-in-range-converter.md | 6 +++++- .../converters/list-to-string-converter.md | 6 +++++- .../converters/math-expression-converter.md | 6 +++++- .../multi-math-expression-converter.md | 6 +++++- docs/maui/converters/text-case-converter.md | 6 +++++- 14 files changed, 91 insertions(+), 14 deletions(-) diff --git a/docs/maui/behaviors/event-to-command-behavior.md b/docs/maui/behaviors/event-to-command-behavior.md index c6c9843e..c5007a17 100644 --- a/docs/maui/behaviors/event-to-command-behavior.md +++ b/docs/maui/behaviors/event-to-command-behavior.md @@ -2,7 +2,7 @@ title: EventToCommandBehavior - .NET MAUI Community Toolkit author: cliffagius description: "The EventToCommandBehavior is a behavior that allows the user to invoke a Command through an event. It is designed to associate Commands to events exposed by controls that were not designed to support Commands. It allows you to map any arbitrary event on a control to a Command." -ms.date: 04/23/2022 +ms.date: 11/10/2026 --- # EventToCommandBehavior @@ -121,6 +121,22 @@ When using this `behavior` with selection or tap events exposed by `ListView` an * [ItemTappedEventArgsConverter](../converters/item-tapped-eventargs-converter.md) * [SelectedItemEventArgsConverter](../converters/selected-item-eventargs-converter.md) +### Setting the culture of the EventArgsConverter + +By default, the `EventToCommandBehavior` passes `CultureInfo.InvariantCulture` to the `EventArgsConverter`. A binding passes `CultureInfo.CurrentUICulture` instead, so this default differs from a binding. Set `EventArgsConverterCulture` to pass a different culture: + +```xaml + + + + + +``` + ## Properties |Property |Type |Description | @@ -129,6 +145,7 @@ When using this `behavior` with selection or tap events exposed by `ListView` an | Command | [ICommand](xref:System.Windows.Input.ICommand) | The `Command` that should be executed. | | CommandParameter | object | An optional parameter to forward to the `Command`. | | EventArgsConverter | IValueConverter | An optional `IValueConverter` that can be used to convert `EventArgs` values to values passed into the `Command`. | +| EventArgsConverterCulture | CultureInfo? | The culture passed to the `EventArgsConverter`. The default is `null`, which means `CultureInfo.InvariantCulture`. | ## Examples diff --git a/docs/maui/converters/color-to-cmyk-string-converter.md b/docs/maui/converters/color-to-cmyk-string-converter.md index 8c917f1c..c11737ac 100644 --- a/docs/maui/converters/color-to-cmyk-string-converter.md +++ b/docs/maui/converters/color-to-cmyk-string-converter.md @@ -2,7 +2,7 @@ title: ColorToCmykStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToCmykStringConverter is a one way converter that allows users to convert a Color value binding to its CMYK string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToCmykStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages with the binding's culture. For example, the percentage separator and the space before the `%` sign follow the culture. + ## Syntax The following examples will show how to use the `ColorToCmykStringConverter` to display the CMYK equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-hsl-string-converter.md b/docs/maui/converters/color-to-hsl-string-converter.md index 30a01263..201ae218 100644 --- a/docs/maui/converters/color-to-hsl-string-converter.md +++ b/docs/maui/converters/color-to-hsl-string-converter.md @@ -2,7 +2,7 @@ title: ColorToHslStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToHslStringConverter is a one way converter that allows users to convert a Color value binding to its HSL string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToHslStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages with the binding's culture. For example, the percentage separator and the space before the `%` sign follow the culture. + ## Syntax The following examples will show how to use the `ColorToHslStringConverter` to display the HSL equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-hsla-string-converter.md b/docs/maui/converters/color-to-hsla-string-converter.md index ea188edf..0cec27e6 100644 --- a/docs/maui/converters/color-to-hsla-string-converter.md +++ b/docs/maui/converters/color-to-hsla-string-converter.md @@ -2,7 +2,7 @@ title: ColorToHslaStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToHslaStringConverter is a one way converter that allows users to convert a Color value binding to its HSLA string equivalent." -ms.date: 04/15/2022 +ms.date: 11/10/2026 --- # ColorToHslaStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the percentages with the binding's culture. For example, the percentage separator and the space before the `%` sign follow the culture. + ## Syntax The following examples will show how to use the `ColorToHslaStringConverter` to display the HSLA equivalent string of a specific `Color`. diff --git a/docs/maui/converters/color-to-rgba-string-converter.md b/docs/maui/converters/color-to-rgba-string-converter.md index 35528442..9cb59abe 100644 --- a/docs/maui/converters/color-to-rgba-string-converter.md +++ b/docs/maui/converters/color-to-rgba-string-converter.md @@ -2,7 +2,7 @@ title: ColorToRgbaStringConverter - .NET MAUI Community Toolkit author: bijington description: "The ColorToRgbaStringConverter is a converter that allows users to convert a Color value binding to its RGBA string equivalent." -ms.date: 02/15/2024 +ms.date: 11/10/2026 --- # ColorToRgbaStringConverter @@ -15,6 +15,10 @@ The `ConvertBack` method returns the RGB `string` `value` converted to a `Color` [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter formats the alpha value with the binding's culture. In a culture that uses a comma as the decimal separator, such as `de-DE`, the alpha value of 0.5 is written as `0,5`. When it converts back, the converter reads the string that it formats itself, using the same culture. + ## Syntax The following examples will show how to use the `ColorToRgbaStringConverter` to display the RGBA equivalent string of a specific `Color`. diff --git a/docs/maui/converters/compare-converter.md b/docs/maui/converters/compare-converter.md index 42f9fea7..6f2b538b 100644 --- a/docs/maui/converters/compare-converter.md +++ b/docs/maui/converters/compare-converter.md @@ -2,7 +2,7 @@ title: CompareConverter - .NET MAUI Community Toolkit author: bijington description: "The CompareConverter is a one way converter that takes an incoming value implementing IComparable, compares to a specified value, and returns the comparison result." -ms.date: 05/17/2022 +ms.date: 11/10/2026 --- # CompareConverter @@ -16,6 +16,10 @@ The `ConvertBack` method is not supported. [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter compares `string` values with the collation of the binding's culture. It compares values of other types without regard to culture. + ## Syntax ### XAML diff --git a/docs/maui/converters/datetimeoffsetconverter.md b/docs/maui/converters/datetimeoffsetconverter.md index 7dfa5cce..eae57dc0 100644 --- a/docs/maui/converters/datetimeoffsetconverter.md +++ b/docs/maui/converters/datetimeoffsetconverter.md @@ -2,7 +2,7 @@ title: DateTimeOffsetConverter - .NET MAUI Community Toolkit author: cliffagius description: "The DateTimeOffsetConverter is a converter that allows users to convert a DateTimeOffset to a DateTime " -ms.date: 03/22/2022 +ms.date: 11/10/2026 --- # DateTimeOffsetConverter @@ -11,6 +11,10 @@ The `DateTimeOffsetConverter` is a converter that allows users to convert a `Dat [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +The converter doesn't use the culture. It no longer applies the calendar of the culture when it converts a `DateTime` back to a `DateTimeOffset`, because the components of a `DateTime` are always Gregorian. + ## Syntax ### XAML diff --git a/docs/maui/converters/double-to-int-converter.md b/docs/maui/converters/double-to-int-converter.md index aa677e3d..23d98a5a 100644 --- a/docs/maui/converters/double-to-int-converter.md +++ b/docs/maui/converters/double-to-int-converter.md @@ -2,7 +2,7 @@ title: DoubleToIntConverter - .NET MAUI Community Toolkit author: bijington description: "The DoubleToIntConverter is a converter that allows users to convert an incoming double value to an int and vice-versa." -ms.date: 03/09/2022 +ms.date: 11/10/2026 --- # DoubleToIntConverter @@ -22,6 +22,10 @@ The `ConvertBack` method returns the supplied `value` converted to a `double` an [!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] +## Culture + +When the `ConverterParameter` is a `string`, the converter parses it with the invariant culture first, so `2.5` in XAML means the same number for every user. If that fails, it parses the string with the binding's culture, so `2,5` works in `de-DE`. + ## Syntax ### XAML diff --git a/docs/maui/converters/index.md b/docs/maui/converters/index.md index 4954c948..e36927da 100644 --- a/docs/maui/converters/index.md +++ b/docs/maui/converters/index.md @@ -2,7 +2,7 @@ title: Converters - .NET MAUI Community Toolkit author: bijington description: The .NET MAUI Community Toolkit provides a collection of pre-built, reusable converters to make developers lives easier. -ms.date: 02/15/2024 +ms.date: 11/10/2026 --- # .NET MAUI Converters @@ -11,6 +11,18 @@ ms.date: 02/15/2024 For further information on Converters please refer to the [.NET MAUI documentation](/dotnet/maui/fundamentals/data-binding/converters). +## Converter culture + +A binding passes a culture to its converter. The culture is the `ConverterCulture` of the binding, or `CultureInfo.CurrentUICulture` when `ConverterCulture` isn't set. In .NET MAUI 11, `Binding` and `MultiBinding` both have a `ConverterCulture` property. + +The following example passes the `de-DE` culture to a converter: + +```xaml +