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 C, you can choose from several dialog boxes.


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 C, you can choose from several prompts.


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 C, you can choose from several toasts.


To use the dialog APIs in your app, you need to link against the correct library by adding the BlackBerry Platform Services (libbps) library to your project.

You must include the following header files from the BPS library:

#include <bps/bps.h>
#include <bps/dialog.h>

Learn more

If you are creating an app using C, you can use the following data types, functions, setters, and getters to manage dialog boxes, prompts, and toasts:

  • Constants in dialog.h: These definitions provide default text for the labels on system dialog boxes.

  • Data types in dialog.h: These data types provide common data structures, typedefs, and enumerations for creating system dialog boxes.

  • General dialog functions: These functions let you display, update, cancel, or destroy dialog boxes. They also provide common functions for receiving dialog events.

  • Dialog setters: These functions can be used to set attributes for all types of dialog boxes.

  • Common dialog event getters: These functions can be used to get attributes for all types of dialog boxes.

Related resources

Last modified: 2015-01-07

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

comments powered by Disqus