Microsoft-ui-xaml: Proposal: Add light dismiss option to ContentDialogs

[Felix-Dev]

Proposal: Add light dismiss option to ContentDialogs

Summary

This proposal aims to add a light dismiss option to the ContentDialog class. The light dismiss behavior is functionally the same as if the user would close the dialog by pressing ESC or the Gamepad B button.

Rationale

Many times, ContentDialogs are displayed which show some information and the user would like to light dismiss the dialog after reading said information. See Windows Terminal's About dialog for example:

It would be great if developers could enable users to light dismiss the dialog in addition to the current dismiss options. Developers who currently want to provide light dismiss behavior for ContentDialogs need to either make use of implementation details or re-build the entire dialog using other controls, like Popup: https://stackoverflow.com/questions/39317526/uwp-light-dismiss-contentdialog.
As such, having a light dismiss behavior to opt-into would enable developers to built great dialog experiences without having to build the dialogs entirely from the ground up or make assumptions about the ContentDialog implementation.

Scope

| Capability | Priority |
| :---------- | :------- |
| Developers can opt-into a light dismiss behavior for a ContentDialog instance. | Must |

Important Notes

The proposed API to add to the ContentDialog class matches the Popup's light dismiss API:

public static DependencyProperty IsLightDismissEnabledProperty { get; }

public bool IsLightDismissEnabled { get; set; }

[shaheedmalik]

Yes. This is needed to make apps more accessible to more input devices.

[ranjeshj]

@stmoy @chigy FYI

[stmoy]

Yes. This is needed to make apps more accessible to more input devices.

@shaheedmalik, can you help me understand how light dismiss dialogs helps with this?

[mdtauk]

Yes. This is needed to make apps more accessible to more input devices.

@shaheedmalik, can you help me understand how light dismiss dialogs helps with this?

It would enable a scenario where you want to display custom Xaml content, which is dismissable without the need of a discreet button. I know this could be achieved as a flyout, but that tends to be for elements that emerges from a control, rather than an About or Progress dialog scenario

[shaheedmalik]

@stmoy Xbox controller compatibility.

[mdtauk]

@stmoy Xbox controller compatibility.

A cancel/dismiss button could be given focus when the dialog opens - for Xbox controller, or enter key press - but not sure why there shouldn't be a DismissBehaviour option which allows for light dismiss, when you may want an overlay that appears modal, but can be dismissed easily.

[stmoy]

@stmoy Xbox controller compatibility.

A cancel/dismiss button could be given focus when the dialog opens - for Xbox controller, or enter key press

Fortunately, the last round of ContentDialog updates included a rationalization about close behavior specifically to support other forms of input. Pressing B on the Gamepad will close the dialog regardless of which button/content has focus. The "close actions" are described in the ContentDialog guidance doc.

Use the ContentDialog.CloseButton API to create this button. This allows you to create the right user experience for all inputs including mouse, keyboard, touch, and gamepad. This experience will happen when:

• The user clicks or taps on the CloseButton
• The user presses the system back button
• The user presses the ESC button on the keyboard
• The user presses Gamepad B

-=-=-

but not sure why there shouldn't be a DismissBehaviour option which allows for light dismiss, when you may want an overlay that appears modal, but can be dismissed easily.

The situation I'm worried about is that some dialogs will then be modal and others will be light-dismiss, but the user will have no way of knowing which is which.

ContentDialogs were built to support scenarios where the app requires the user's attention/input. They are modal, after all, and block the user until they act. The question then becomes “Is a light dismiss action deliberate enough to justify closing a dialog?” Light dismiss is intended to be a lightweight user interaction this is used to dismiss non-crucial UIs -- and is therefore not deliberate enough of a user action to close a dialog.

The About info dialog above isn't following the ContentDialog guidance because A) it's not requesting a user action, and B) the information isn't critical. In other words, this seems like a user experience issue with Terminal that we should fix rather than introducing a confusing new dialog user experience API across the system.

[Felix-Dev]

@stmoy Please correct me if I'm wrong, but if ContentDialog won't get a light dismiss option, then the platform is lacking a fast and easy way to create light dismissable dialogs. Yes, you can use the Popup class but that's not ready-made for you like the ContentDialog is.

I think the platform should definitely have a ContentDialog class like API to easily create dialogs which can be closed by a lightweight user action. I've seen a lot of (content) dialogs which only showed some information and had an OK button. These should be light dismissable. ContentDialog per its guidlines might be the wrong control here but developers are using it because it's so much easier to create a light-dismissable dialog using the Popup class.

It's possible already to build dialogs using the Popup class and the ContentDiaog class which look the same to the user (so they cannot differentiate between them). One such dialog can be light dismissed (the Popup one), the ContentDialog dialog cannot. In that sense the user might already be confused that some dialogs can be light-dismissed, others not. Clear UI design in the apps can help avoid confusing the user.

TL;DR: Developers today are using the ContentDialog class in a way which might not abide by its guidelines because the lack of another API to easily and rapidly create dialog experiences. There is the Popup class but it forces you to build the entire dialog UI from the ground up. As there are many types of dialogs which only display some information and don't require a choice from the user, the platform should offer a simple and easy way to create light dismissable dialogs.

[mdtauk]

I think a good way to think about ContentDialog, is that it creates a Dialog which you add content to. Its not a ContentModalDialog, and as such, there is nothing wrong with allowing it to be Modal or Overlay as a display mode, and let the developer choose how it can be dismissed.

[Felix-Dev]

@mdtauk I agree. ContentDialog should cover both worlds. For that, the guidelines @stmoy is talking about need to be slightly changed:

Use a ContentDialog to request input from the user, or to show information in a modal dialog.
(https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.contentdialog)

I think that will be the easiest solution because there really are both modal and non-modal dialogs out there and ContentDialog class sounds like it should cover both types.

[mdtauk]

@mdtauk I agree. ContentDialog should cover both worlds. For that, the guidlines @stmoy is talking about need to be slightly changed:

Use a ContentDialog to request input from the user, or to show information in a modal dialog.
(https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.contentdialog)

I think that will be the easiest solution because there really are both modal and non-modal dialogs out there and ContentDialog class sounds like it should cover both types.

By default the Dialog creates a button that will close the Dialog. If there was a Dismiss Behaviour property, and Light-Dismiss was chosen, that close button should not appear by default.

The guidance should change to reflect that new possibility, and apps like Terminal and Calculator which use an "About Dialog" should use the same behaviour and control.

[stmoy]

TL;DR: Developers today are using the ContentDialog class in a way which might not abide by its guidelines because the lack of another API to easily and rapidly create dialog experiences. There is the Popup class but it forces you to build the entire dialog UI from the ground up. As there are many types of dialogs which only display some information and don't require a choice from the user, the platform should offer a simple and easy way to create light dismissable dialogs.

Thanks both @Felix-Dev and @mdtauk for helping to explain further. To recap what I think I'm hearing: The heart of the issue here is that people want to build lightweight dialog experiences (like the About dialog above). It's _possible_ to make these experiences today using Popup, but you're starting from 0. ContentDialog is also an option, but it's a modal and heavyweight option.

Before we come up with a specific API proposal, it's important to understand the scenarios. For example, @mdtauk mentions dialogs without buttons or progress dialogs above. It'd be helpful if y'all could help list a these scenarios so we can track them and compare their user experiences. What I think we might find is that we need a new visual affordance/control that has the similar ease-of-use as ContentDialog, but looks different enough that users aren't confused.

TL;DR - you've helped convince me of the developer need for a light-dismissable dialog widget. I still don't adding an API to ContentDialog is the way to go until we understand the scenarios and see if ContentDialog actually fits. I need your help enumerating where you would use this light-dismissable dialog widget.

[yaichenbaum]

An example where I would like the Light-Dismiss option is for the GoTo Dialog in Quick Pad. The user can take an action here but can cancel as well. Having a light dismiss option will provide another way for the user to close the dialog and get back to the app.

[mdtauk]

ContentDialog as a name, is open ended enough to cover multiple kinds of dialogs. So adding a behaviour enum allows for expanding in the future.

For the scenarios, it may be good to look at Win32 practices as well as potential UWP cases.

And there will be some overlap between things like the #913 Long-Lived Status Message, #622 Toast message, #638 TeachingTip V2 options, and MessageDialog.

My suggestion was taking the assumption the control behaviour _should_ exist and extrapolating what it could be used for.

A quick thought about all this from me, ordered by the "weight"...

• _Toasts_ are temporary, shown by the app not user action, and act as a note to the user, but is not critical information, self-dismisses;
• _Status Messages_ are, shown by the app not user action, displays important information that could/should be dismissed, but should not prevent the use of the app whilst displayed;
• _Teaching Tips_ shown by the app, not user action, should alert and inform a user about functionality. The information will get in the way, but can be dismissed without consequence;
• _MessageDialogs_ should really not be used, but is shown via a user action, allows a message which is movable on the screen, outside of the app space so doesn't have to obscure the app, but must be dismissed with or without consequence;

• _(Modal)ContentDialog_ is typically user initiated - the user did an action to show the Dialog - demands a user's attention with important information, could involve a request for input, and involves a cognitive committal to remove it;

• _(Light Dismiss)ContentDialog_ is typically user initiated, would grab a user's attention, provide important-ish information, could request user input, but can be dismissed without a committal, and only affects the app state if input is placed?

What distinguishes this control mode, from the Toast, Status Message, and Teaching Tip, is that it only shows when a user performs an action to summon it, and it obscures the view of the app.

What distinguishes it from the Modal and Message Dialogs, is that it doesn't require a commitment action, which could or could not alter the state of the app.

[chingucoding]

My 2cents: Something that indeed is problematic, is how to make clear that a dialog is light dismissable or not. I am slowly thinking, that it might be better to just introduce another control specifically designed for light dismissable popup, so that devs don't have to use popup and start from 0.

A good example for that are information dialogs, such as the use case of the terminal (which shouldn't have used contentdialog according to guidelines).

Another example might be a success/failure dialog after long operations to report what happened, e.g. after compiling, to show whether there were errors or not.

[Felix-Dev]

@Chingucoding Instead of a new dialog control, perhaps we ca add a visual clue to the ContentDialog to indicate a dialog requires user attention/input?

In Win32, the border flickers quickly three times (I believe) and a sound is played if the user clicks outside the modal dialog area, clearly showing user input is required. Yes, the user won't see that up-front but once they did click the area outside the dialog, they will notice that their attention/input is required. And since this closely models current Win32 behavior many users will be familiar with this visual clue.

The reason why I don't think we need a new control but should instead strive to bake modal and non-modal dialogs into the current ContentDialog class is that they will both be quite similar, The new light dismiss control should ideally have the same ContentDialog properties like Title, Content, Primary/Secondary button properties, the same styling support (TitleTemplate/ContentTemplate/PrimaryButtonStyle/...) and support for darkening the app area outside the dialog. As such, if not more glarring API dfferences will materialize during this discussion, for simplicity, I would just extend the current DialogControl class with a light dismiss property. Also add a visual clue (perhaps via the border) to aid the user in understanding the nature of the ContentDialog in front of them.

Referencing @mdtauk as our design expert to see what visual clues he might can think of.

[mdtauk]

Initial thought @Felix-Dev for a visual clue, could be a slowly fading in and out Color Opacity animation on the smoke layer behind the dialog. Say moving back and forth between 30% and 40% opacity, so it invites the user to tap on it.

[mdtauk]

A good example for that are information dialogs, such as the use case of the terminal (which shouldn't have used contentdialog according to guidelines).

I suspect both Calculator and Terminal will move their About information into settings pages, when settings UI are added to both these apps.

But there are many many Win32 apps with About Boxes, so its a classic dev pattern, that may see a resurgence as Xaml starts to replace old GDI UIs

[Felix-Dev]

@stmoy Summing up, for now we have two suggestions about possible visual clues to help the user knowing if a ContentDialog facing them is light dismissable or not:

1) If a content dialog is not light dismissable and the user clicks on the smoke layer in the background the border flashes multiple times and a sound is played. This behavior mimics the well-known Win32 app behavior when clicking outside of a modal dialog in an app and thus will be familiar to users. A potential shortcoming of this approach is that the user does not notice the dialog type (modal or not) they are looking at without having first tried to dismiss it.
2) If a content dialiog is light dimissable, the smoke layer in the background is fading in and out slightly inviting the user to tap on it. Its advantage is that the user will notice the dialog type just by looking at the screen. Potential disadvantages are that a) this should be an unfamilar behavior in Windows to differentiate between modal and non-modal dialogs and b) perhaps it could add some small amount of visual distraction (not sure on that one, a demo of this behavior will tell us more and the fade in/out amount could always be tweaked).

Thoughts?

[mdtauk]

I would go for a slow pulsating/throbbing smoke layer, which acts like it is inviting a click/tap.

The Win32 modal flash feels a little heavy handed, and tied to the older framework. It also would have to apply to all modal UI to be consistent.

AFAIK, this light dismiss Content Dialog will be the only full screen obscuring Light Dismiss control - so can set its own visual cues.

[chingucoding]

In my opinion, flashing/fading is not a good idea to indicate that something is light dismissible/not dismissible. For light dismiss, we could add an x in the top right to indicate users can easily click away the notification, though this also seems a bit old. This is really a tough question.

[stmoy]

One thing to keep in mind: visual accessibility. We'd need to be very sensitive/deliberate about the visual affordance especially for folks that have a harder time differentiating between changes in color.

The ContentDialog smoke layer is unique within the Xaml platform and specifically designates that the dialog is modal. Our other light-dismiss surfaces don't have a smoke layer. I'd suspect that the easiest and most consistent thing to do if a dialog is light-dismissible would be to not have a smoke layer at all. A new pulsing smoke layer would be unique in the system and I'm concerned that it would draw even more attention to the light-dismissible dialog than its modal counterpart.

I still don't know if adding a knob to ContentDialog is the right way to go, although I am inclined to agree that if we add a "LightDismissDialog" or something, that many of the properties on it would be the same.

[mdtauk]

I share some of your concern about making it a paradigm and how that affects perception and accessibility. The smoke layer does draw attention, and also makes the rest of the UI visually unavailable to touch.

Not having some kind of separation for the Content Dialog and the UI could look like a rendering error. Maybe an exaggerated shadow would work like the smoke, but not obscuring the entire UI. For Accessibility and High Contrast some kind of border differentiation could be used.

Visually the information displayed should be of equal importance to convey, the only difference would be one requires User interaction with a choice, the other can be dismissed without potentially destructive or final consequence.

I can think of other, better ways to present the examples that came to mind such as the user clicking a button to display progress or status of a background action (although they would require the #913 control to be added)

[Felix-Dev]

One thing to keep in mind: visual accessibility. We'd need to be very sensitive/deliberate about the visual affordance especially for folks that have a harder time differentiating between changes in color.

In the win32-based behavior, we can play with at least three dimensions to make it noticeable that user input is required if they try to light dismiss a modal dialog: border color, border thickness and sound.

I really don't want to add a new visual feedback style here unknown to Windows users (fading in/out of the smoke layer).

Right now, I'm in favor of having the smoke layer in either case (also see related issue #858 if the smoke layer shouldn't be displayed for non-modal dialogs) and showing a close button in the top-right corner of each non-modal ContentDialog.