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. The BlackBerry 10 Native SDK 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.

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 toast, which does not require interaction if it does not contain an optional button.

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

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.

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

If you are creating an app using QML or C++, you can choose from several dialog boxes or you can customize a dialog box to suit your app.

  • 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. To create a standard dialog box, use the SystemDialog class. To learn more, see Creating a dialog box.

  • A SystemProgressDialog is a dialog box that provides the user with an indication of the progress of an activity. To create a progress dialog box, use the SystemProgressDialog class. 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. To create a list dialog box, use the SystemListDialog class. 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 information to provide.

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. Prompts are useful for requesting information such as file names, login credentials, and passwords.

Screen showing a prompt with two standard buttons.

If you are creating an app using QML or C++, you can choose from several prompts.

  • A SystemPrompt is a dialog box with two default buttons for accepting or rejecting the dialog box, and a field for receiving input from the user. To create a standard prompt, use the SystemPrompt class. For more information, see Creating a 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 create a credentials prompt, use the SystemCredentialsPrompt class. To learn more, see Creating a credentials prompt.

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. A progress toast is a special type of toast that tells the user about the progress of an activity.

For example, you can use a toast to tell the user something informative that doesn't need any action, such as, you've just saved a message.

Screen showing a system toast on a device with a dark theme.

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 only when you are asking the user if they would like to undo a deletion.

If you are creating an app using QML or C++, you can choose from several toasts.

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.

Prerequisites

Dialog classes are included in the bb::system library. To use system classes in your app, you must add the following to the .pro file in your project:

LIBS += -lbbsystem

Dialog classes are included in the bb::system library. To use system classes in your app, you must add the following to the .pro file in your project:

LIBS += -lbbsystem

Learn more

If you are creating an app using QML or C++, 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

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus