Dialog boxes, prompts, and toasts

Sometimes you need to pause and communicate important information about the progress of an action or the activity in an app before the user can continue. Cascades provides a flexible way to interrupt the UI flow and communicate with the user by using dialog boxes.

You can use dialog boxes to ask the user to confirm an action, notify the user of an event, or prompt the user for additional information. Because dialog boxes disrupt the flow of the UI, you should use them only as a last resort. In most cases, you should integrate confirmation, feedback, and prompts directly into your app.

Cascades dialog boxes are modal; users must provide a response before they can continue to interact with the window associated with the dialog box. The exception to this convention is the SystemToast, which does not require interaction if it does not contain an optional SystemUiButton.

To learn more about the guidelines for interrupting the UI flow with dialog boxes, see Notifications.

System dialog boxes

A dialog box displays information and a set of buttons to accept or cancel the actions presented by the dialog box. You can use a basic dialog box to ask the user to confirm irreversible, destructive, or expensive actions. As a best practice, you should present the body of a dialog box in the form of a question.

For example, you can display a dialog box to indicate that your app is synchronizing all user contacts and ask for the user's confirmation to continue. In Cascades, you can choose from several system dialog boxes or you can customize a dialog box to suit your app.

Screen showing a system dialog with two standard buttons and an optional custom button.

You can use the SystemDialog class to create a standard dialog box. A SystemDialog is a dialog box with informative text and a set of buttons. There are two default buttons for accepting and rejecting the dialog box, and you can add customized buttons.

A SystemProgressDialog is a dialog box that provides the user with an indication of the progress of an activity. You can use the SystemProgressDialog class to create a progress dialog box. To learn more, see Creating a progress dialog box.

A SystemListDialog is a dialog box with a list of choices, and it supports individual selection or multiple selection of items. You can use the SystemListDialog class to create a list dialog box. To learn more, see Creating a list dialog box.

Prompts

A prompt is a dialog box that requests input from the user. A prompt doesn't have any informative text. The title of the prompt should clearly tell the user what to provide in the input field.

For example, you can display a prompt that asks for the answer to a simple question that doesn't need any explanation in the body of the dialog box. The text field on a prompt can be empty or prepopulated. If the prompt is prepopulated, the text is selected. This approach can be useful if your app needs to ask for a file name.

Screen showing a system prompt with two standard buttons.

You can use the SystemPrompt class to create a standard prompt. A SystemPrompt is a dialog box with two default buttons for accepting and rejecting the dialog box, and an input field for receiving input from the user.

A credentials prompt is a special type of prompt that asks the user to enter a username and password. You can use the SystemCredentialsPrompt class to create a credentials prompt. A SystemCredentialsPrompt also contains a check box to specify whether to display the password as it is typed (or have it masked) and a check box to specify whether to remember the password. To learn more, see Creating a system credentials prompt in C++.

Toasts

A toast is a simple pop-up message that appears in your app and expires after a predefined amount of time. The user doesn't have to interact with a toast. A toast can contain text, an icon, or a combination of both.

For example, you can use a toast to tell the user that something will expire in your app.

You can use the SystemToast class to create a standard toast that displays information for a predefined amount of time (the timeout period) and then disappears automatically.

Screen showing a system toast on a device with a physical keyboard.

You can add a button to a toast. If a toast includes a button, the timeout period starts after the user taps the screen. If the user taps the button, the toast disappears immediately. Toasts that contain buttons interrupt the UI flow so they should be used in special cases. As a best practice, you should use a toast with a button when you are asking the user if they would like to undo a deletion.

A progress toast is a special type of toast that gives tells the user about the progress of an activity. You can use the SystemProgressToast class to create a progress toast. To learn more, see Creating a progress toast.

Custom dialog boxes

A custom dialog box can be any combination of Cascades controls that you can imagine. You can build your custom dialog box using custom colors, fonts, images, and more.

You can use the Dialog class to create a customized dialog box. A Dialog occupies the entire screen and can be placed on top of your UI to present information to the user temporarily. The Dialog class inherits from the AbstractDialog class.

Screen showing a custom dialog box on a device with a physical keyboard.

If you want to reuse your custom dialog box, you can create it as a QML component. To learn more about reusable components, see Custom QML components.

Custom dialog boxes should be used only when a system dialog box doesn't highlight the information that you want to display.

You can use the following classes to manage dialog boxes, prompts, and toasts:

  • SystemUiButton: The SystemUiButton class represents a button that appears on your dialog box. This button has a label and a property that indicates whether the button is displayed.

  • SystemUiError: The SystemUiError class is an enumerated type for all of the errors that can be returned when your app displays a dialog box.

  • SystemUiInputField: A SystemUiInputField class represents an input field that requests input from the user. An input field has a label, default text to show to the user, and text to show to the user if the user forgets to provide input.

  • SystemUiInputMode: The SystemUiInputMode class is an enumerated type that describes what types of input a field accepts (for example, email addresses, passwords, phone numbers, PINs, or web addresses).

  • SystemUiModality: The SystemUiModality class is an enumerated type that specifies that the UI is either modal for the application or modal for all applications.

  • SystemUiPosition: The SystemUiPosition class is an enumerated type that provides the possible positions of UI components in a dialog box (for example, top, middle, or bottom center).

  • SystemUiProgressState: The SystemUiProgressState class is an enumerated type that provides the possible states of an activity in progress (for example, active, inactive, or error).

  • SystemUiResult: The SystemUiResult class is an enumerated type that lists the possible results of a UI request, such as which button was selected, whether a request for input expired, or if an error occurred waiting for input.

  • SystemUiReturnKeyAction: The SystemUiReturnKeyAction class is an enumerated type that lists the possible actions to associate with the Return key.

Related resources

Web-based training

Design guidelines

Sample apps

Last modified: 2013-12-21

comments powered by Disqus