Feature/maui/sl popup v2 #552
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR updates the documentation for creating and using popups in .NET MAUI with the Community Toolkit, including new examples for popup results, options, and the popup service. Key changes include:
- Adding comprehensive usage examples for creating and awaiting popup results in both XAML and C#
- Updating the popup service documentation to reflect the use of ContentView and current navigation
- Enhancing the Popup documentation with revised code snippets and additional context for programmatically closing popups
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/maui/views/popup/popup-result.md | New documentation and code examples for returning a result from a popup. |
| docs/maui/views/popup/popup-options.md | Documentation for customizing popup appearance and behavior with PopupOptions. |
| docs/maui/views/popup-service.md | Revised examples to ensure current page retrieval and proper popup presentation. |
| docs/maui/views/Popup.md | Updated documentation and examples for building and presenting popups. |
|
Learn Build status updates of commit 9b22c64:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/maui/views/popup/popup-options.md | View | Details | |
| docs/maui/views/popup/popup-result.md | View | Details | |
| docs/maui/views/popup-service.md | 💡Suggestion | View | Details |
| docs/maui/views/Popup.md | ✅Succeeded | View |
docs/maui/views/popup/popup-options.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading.
docs/maui/views/popup/popup-result.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading. - Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'.
docs/maui/views/popup-service.md
- Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'. - Line 144, Column 465: [Suggestion: preserve-view-not-set - See documentation]
You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /dotnet/maui/fundamentals/shell/navigation?view=net-maui-9.0#process-navigation-data-using-a-single-method
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
Co-authored-by: Pedro Jesus <[email protected]>
…ftDocs/CommunityToolkit into feature/maui/sl-popup-v2
|
Learn Build status updates of commit 03f6e47:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/maui/views/popup/popup-options.md | View | Details | |
| docs/maui/views/popup/popup-result.md | View | Details | |
| docs/maui/views/popup-service.md | 💡Suggestion | View | Details |
| docs/maui/views/Popup.md | ✅Succeeded | View |
docs/maui/views/popup/popup-options.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading.
docs/maui/views/popup/popup-result.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading. - Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'.
docs/maui/views/popup-service.md
- Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'. - Line 144, Column 465: [Suggestion: preserve-view-not-set - See documentation]
You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /dotnet/maui/fundamentals/shell/navigation?view=net-maui-9.0#process-navigation-data-using-a-single-method
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit 4859773:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/maui/views/popup/popup-options.md | View | Details | |
| docs/maui/views/popup/popup-result.md | View | Details | |
| docs/maui/views/popup-service.md | 💡Suggestion | View | Details |
| docs/maui/views/Popup.md | ✅Succeeded | View |
docs/maui/views/popup/popup-options.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading.
docs/maui/views/popup/popup-result.md
- Line 0, Column 0: [Warning: h1-missing - See documentation]
H1 is required. Use a single hash (#) followed by a space to create your top-level heading. - Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'.
docs/maui/views/popup-service.md
- Line 4, Column 14: [Suggestion: duplicate-descriptions - See documentation]
Attribute 'description' with value 'The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.' is duplicated in 'maui/views/popup-service.md(4,14)', 'maui/views/popup/popup-result.md(4,14)'. - Line 134, Column 465: [Suggestion: preserve-view-not-set - See documentation]
You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /dotnet/maui/fundamentals/shell/navigation?view=net-maui-9.0#process-navigation-data-using-a-single-method
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit 0b8bb9e: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit 5cfe8ed: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit 35dffbe: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit dcb12b0: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
There was a problem hiding this comment.
Thanks Shaun!!! Reviewing these docs highlighted two things to me:
- There was a bug where
PopupDefaultswere not being properly applied to when not inheriting fromPopup - There was a missing feature where developers could not close a Popup programmatically when not inheriting from
Popupand/or when not usingPopupService
1. PopupDefaults Bug (Fixed)
I just now pushed a bug fix where PopupDefaults.Padding (new Thickness(15)), PopupDefaults.HorizontalOptions (LayoutOptions.Center) and PopupDefaults.VerticalOptions (LayoutOptions.Center) are now applied when passing in an IView to ShowPopup().
My goal is that the default Popup should both look good and "just work" out of the box.
Could you update the screenshots for popup-basic.png? I've left a commend on popup-basic.png below where I added a screenshot from my Android emulator that shows how it looks now: #552 (comment)
2. New PR for PopupExtensions.ClosePopup()
I've opened a PR that adds PopupExtensions.ClosePopup() that I explain more in the Closing a Popup section: #552 (comment)
There was a problem hiding this comment.
Whoops - I almost forgot to review the PopupService docs!
I cant comment directly on the sections that haven't been updated, but we do need to update the Closing a Popup section:
PopupService.ClosePopupAsync() method names
- Line 194. shows
popupService.ClosePopup()instead ofpopupService.CloseAsync()
The PopupService provides the ClosePopup and ClosePopupAsync methods that make it possible to close a Popup from a view model.
- We no longer have
ClosePopup - Let's update this to "The
PopupServiceprovides theClosePopupAsyncmethod that make it possible to close aPopupfrom a view model."
Great spot! Now to follow-up with a question from my side. I see we have |
|
Learn Build status updates of commit a87ce93: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
No need because FYI - I just renamed |
|
I meant on |
Ah - got it. I'll add the following method signatures now to public Task ClosePopupAsync(Page page, CancellationToken cancellationToken = default);
public Task ClosePopupAsync<T>(Page page, T result, CancellationToken cancellationToken = default);This'll allow Update: Done ✅ CommunityToolkit/Maui@d2b499b |
|
Learn Build status updates of commit b979369: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit eafdfa0: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit cb7f271: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit 9fc7158: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
Co-authored-by: Brandon Minnick <[email protected]>
|
Learn Build status updates of commit 4dec735: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
There was a problem hiding this comment.
Pull Request Overview
This PR updates the documentation for the .NET MAUI Community Toolkit popups (v2) to improve clarity on returning values, customizing popup behavior, and using the Popup service.
- Adds new documentation for returning a value from a Popup.
- Introduces comprehensive examples for PopupOptions customization.
- Updates Popup and PopupService examples to reflect API changes and proper navigation parameters.
Reviewed Changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| docs/maui/views/popup/popup-result.md | New content explaining how to return values from a Popup. |
| docs/maui/views/popup/popup-options.md | New documentation on customizing popup appearance and behavior. |
| docs/maui/views/popup-service.md | Updated examples demonstrating PopupService with current navigation. |
| docs/maui/views/Popup.md | Revised examples switching from toolkit:Popup to ContentView and updated close handling. |
| docs/maui/TOC.yml | Updated table of contents with new sections for PopupOptions and Popup results. |
Comments suppressed due to low confidence (2)
docs/maui/views/popup-service.md:21
- Ensure the documentation clearly explains the change from using toolkit:Popup to ContentView in XAML examples, to avoid confusion regarding which type to inherit from when creating a popup.
<ContentView ...>
docs/maui/views/Popup.md:150
- Verify that the newly introduced asynchronous method for closing the popup (ClosePopup) correctly awaits the dismissal animation and consider renaming it to ClosePopupAsync to clearly indicate its asynchronous behavior.
await this.ClosePopup(cts.Token);
There was a problem hiding this comment.
Hey Shaun! I have a couple changes I'd like to make to the Popup docs. Since these changes are pretty wide-sweeping, I'll drop the re-write here in this Review comment:
- I've corrected the
Close Popupsection to use the updated APIs - Let's tell a better, simpler, story that first highlights how easy it is now to display a popup in just one line of code:
this.ShowPopupAsync(new Label { Text = "Hello World" });
- We should still show how to build a Popup in XAML
- We don't need to tell folks how to build a popup in C# thanks to the first/simple example above.
- Let's squeeze in additional
PopupOptionsexamples in the Popup docs- This ensures that folks don't accidentally overlook the
IPopupOptionsparameter since it is easily missed as a given it is a default parameter - I anticipate devs who already use Popup will be confused by the new Border/Shadow/Shape/etc and it'll be far easier to point them to the docs as long as we include glaring examples in both the Popup docs and the PopupOptions docs
- This ensures that folks don't accidentally overlook the
Popup.md
---
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
---
# Popup
Popups are a common way of presenting information to a user that relates to their current task. Operating systems provide a way to show a message and require a response from the user, these alerts are typically restrictive in terms of the content a developer can provide and also the layout and appearance.
> [!NOTE]
> If you wish to present something to the user that is more subtle then checkout our [Toast](../alerts/toast.md) and [Snackbar](../alerts/snackbar.md) options.
The `Popup` view allows developers to build their own custom UI and present it to their users.
The .NET MAUI Community Toolkit provides 2 approaches to create a `Popup` that can be shown in a .NET MAUI application. These approaches will depend on the use case. This page focuses on the simplest form of `Popup` - simply rendering an overlay in an application, for the more advanced approach enabling the ability to return a result from the `Popup` please refer to [Popup - Returning a result](./popup/popup-result.md).
## Displaying a Popup
The .NET MAUI Community Toolkit provides multiple approaches to display a `Popup` in a .NET MAUI application:
1. In a `ContentPage`, call to the `this.ShowPopupAsync()` extension method, passing in a `View` to display in the Popup
- **Note:** To further customize a Popup, please refer to the [**PopupOptions** documentation](./popup-options).
2. Returning a result from the `Popup`
- Please refer to the [**Popup - Returning a result** documentation](./popup/popup-result.md).
3. Using the `PopupService`
- Please refer to the [**PopupService** documentation](./popup-service.md).
The documentation below demonstrates the simplest way to display a Popup using the `.ShowPopupAsync()` extension method. This method returns a `Task<IPopupResult>` that will complete when the Popup closes. The `PopupOptions` provided are optional.
```cs
public class MainPage : ContentPage
{
// ...
async void DisplayPopupButtonClicked(object? sender, EventArgs e)
{
await this.ShowPopupAsync(new Label
{
Text = "This is a very important message!"
}, new PopupOptions
{
CanBeDismissedByTappingOutsideOfPopup = false,
Shape = new RoundRectangle
{
CornerRadius = new CornerRadius(20, 20, 20, 20),
StrokeThickness = 2,
Stroke = Colors.LightGray
}
})
/**** Alternatively, Shell.Current can be used to display a Popup
await Shell.Current.ShowPopupAsync(new Label
{
Text = "This is a very important message!"
}, new PopupOptions
{
CanBeDismissedByTappingOutsideOfPopup = false,
Shape = new RoundRectangle
{
CornerRadius = new CornerRadius(20, 20, 20, 20),
StrokeThickness = 2,
Stroke = Colors.LightGray
}
})
****/
}
}
Alternatively, a Popup can be created in XAML or C# and passed into ShowPopupAsync().
Building a Popup in XAML
The easiest way to create a Popup is to add a new .NET MAUI ContentView (XAML) to your project. This will create 2 files: a *.xaml file and a *.xaml.cs file.
Replace the contents of *.xaml with the following:
<ContentView
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MyProject.SimplePopup"
Padding="10">
<Label Text="This is a very important message!" />
</ContentView>The default values for HorizontalOptions and VerticalOptions will result in the Popup being displayed in the center of page that it overlays.
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.
Presenting a Popup Created in XAML
Once the Popup has been created in XAML, it can then be presented through the use of the Popup extension methods used on a Page, Shell or an INavigation, or through the IPopupService implementation from this toolkit.
The following example shows how to instantiate and show the SimplePopup created in the previous example through an extension method on a ContentPage.
using CommunityToolkit.Maui.Views;
public class MyPage : ContentPage
{
public async Task DisplayPopup(CancellationToken token)
{
var popup = new SimplePopup();
await this.ShowPopupAsync(popup, PopupOptions.Empty, token);
}
}
Closing a Popup
There are 2 different ways that a Popup can be closed:
- A Popup can be closed programmatically
- A Popup can be closed when a user taps outside of the popup
- Note To prevent a Popup from closing when a user taps outside of it, set
PopupOptions.CanBeDismissedByTappingOutsideOfPopuptofalse
- Note To prevent a Popup from closing when a user taps outside of it, set
1. Programmatically closing a Popup
There are 3 options to close a Popup programatically:
- In a
ContentPage, use thethis.ClosePopupAsync()extension method - In an app using
Shell, useShell.Current.ClosePopupAsync()extension method - Use the
PopupService- Please refer to the PopupService documentation.
In the example below, we demonstrate how to use the this.ClosePopupAsync() in a ContentPage. To learn how to use PopupService to close a Popup, please refer to the PopupService documentation.
using CommunityToolkit.Maui.Views;
public class MyPage : ContentPage
{
public async Task DisplayAutomaticallyClosingPopup(Timespan displayTimeSpan, CancellationToken token)
{
var popup = new SimplePopup();
// This Popup is be closed automatically after 2 seconds
this.ShowPopup(popup, new PopupOptions
{
CanBeDismissedByTappingOutsideOfPopup = false
});
await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);
await this.ClosePopupAsync(token);
/**** Alternatively, Shell.Current can be used to close a Popup
Shell.Current.ShowPopup(popup, new PopupOptions
{
CanBeDismissedByTappingOutsideOfPopup = false
});
await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);
await Shell.Current.ClosePopupAsync(token);
***/
}
}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 for more details.
PopupOptions
The PageOverlayColor, Shape, Shadow can all be customized for Popup. See PopupOptions for more details.
Events
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. |
Examples
You can find an example of this feature in action in the .NET MAUI Community Toolkit Sample Application.
API
You can find the source code for Popup over on the .NET MAUI Community Toolkit GitHub repository.
Additional Resources
|
@TheCodeTraveler I have applied the changes as you suggested. Let me know your thoughts. |
|
Learn Build status updates of commit 44f1206:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/maui/views/popup-service.md | View | Details | |
| docs/maui/views/Popup.md | View | Details | |
| docs/maui/images/views/popup/popup-blue-border.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-green-shadow.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-no-border.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-no-shadow.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-page-overlay-opaque.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-page-overlay-translucent.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-result.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-with-button.png | ✅Succeeded | View | |
| docs/maui/images/views/popup/popup-with-padding.png | ✅Succeeded | View | |
| docs/maui/TOC.yml | ✅Succeeded | View | |
| docs/maui/views/popup/popup-options.md | ✅Succeeded | View | |
| docs/maui/views/popup/popup-result.md | ✅Succeeded | View |
docs/maui/views/popup-service.md
- Line 16, Column 126: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#defining-your-popup' in 'maui/views/Popup.md'.
docs/maui/views/Popup.md
- Line 24, Column 67: [Warning: file-not-found - See documentation]
Invalid file link: './popup-options'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
No description provided.