Dialog boxes

A dialog box is standard across all BlackBerry 10 apps. These dialog boxes have a default look and feel, including positioning and behavior of the buttons on the dialog box.

A dialog box closes after the user presses one of its buttons. If the dialog box is no longer required by your app, you should clean up its resources. If your app cleans up while the dialog box is visible, the dialog box closes and its resources are freed.

Screen showing a system dialog box.

To learn more about best practices for the positioning of the buttons and how to label them, see Notifications in the UI Guidelines.

It is a good practice to keep button labels short. Long button labels might not be fully visible.

A SystemDialog conveys information to the user and can provide the user with a choice. A SystemDialog has one or more buttons. By default, the OK button and the Cancel button are created automatically using the constructor. These two buttons emit the finished() signal when they're tapped. The OK button returns ConfirmButtonSelection in the SystemUiResult, while the Cancel button returns CancelButtonSelection.

Screen showing the OK button on a system dialog box.

Screen showing the Cancel button on a system dialog.

Creating a dialog box

In the code sample below, the bb.system 1.0 library is imported and a SystemDialog is added as an attached object to a Button. When the user taps the button, the onClicked signal handler calls the show() function on the SystemDialog to display the dialog box. The default buttons appear in the system dialog box because no text is specified for them.

Screen showing a system dialog box created in QML.

A SystemToast has also been added as an attached object. When the user taps a button in the dialog box, the code checks to see which button was tapped and displays a toast when the user taps the Cancel button.

import bb.cascades 1.0
import bb.system 1.0

// This sample creates a basic SystemDialog as an attached object.

Page {
    content: Container {
        layout: DockLayout {
        }
        Container {
            horizontalAlignment: HorizontalAlignment.Center
            verticalAlignment: VerticalAlignment.Center

            Button {
                text: "First time?"
                attachedObjects: [
                    SystemToast {
                        id: myQmlToast
                        body: "So long! Thanks for coming ...!"
                        onFinished: {
                            Application.quit();
                        }
                    },
                    SystemDialog {
                        id: myQmlDialog
                        title: "Friendly Warning"
                        body: "Games can be habit-forming... "
                        onFinished: {
                            if (myQmlDialog.result == 
                                  SystemUiResult.CancelButtonSelection)
                            	myQmlToast.show();
                        }
                    }
                ]
                onClicked: {
                    myQmlDialog.show()
                }
            } // button
        } // end Container
    } // end Container
}// end Page

A SystemDialog is displayed using the show() function and dismissed using the cancel() function. If you want your UI to block until the user taps a button on your dialog box, you can use the exec() slot to display the SystemDialog in your UI. You can also configure a SystemDialog to disappear automatically by using the dismissAutomatically property. Using the dismissAutomatically property doesn't release the SystemDialog from memory.

A SystemDialog emits signals when the user performs an action or when a property of the SystemDialog changes. For example, the finished() signal is emitted when the user taps the OK button or the Cancel button.

To determine which button was tapped, you can use the SystemUiResult class. The finished() signal includes the result parameter, which indicates the button that the user tapped. The CustomButtonSelection value is returned in the SystemUiResult when a custom button is tapped.

You can create a SystemDialog in C++ and use the show() function to display it in your UI. A C++ code sample that shows you how to create a SystemDialog is shown below. 

This SystemDialog has an extra button to demonstrate the position of each button. The SystemDialog is dismissed automatically when the user taps one of the buttons.

Screen showing a system dialog box on a device with a physical keyboard.
#include "applicationui.hpp"

#include <bb/cascades/Application>
#include <bb/cascades/QmlDocument>
#include <bb/cascades/AbstractPane>
#include <bb/cascades/LocaleHandler>
#include <QObject>
#include <bb/cascades/AbstractPane>
#include <bb/system/SystemDialog>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
// A public function to display a SystemDialog in your UI
void App::showDialog() 
{

    // Set up the SystemDialog with a title and some body text.
    // Label the two standard buttons with specific text.
    // Add a custom button as well.

	SystemDialog *dialog = new SystemDialog("Save as", 
                                            "Discard changes", 
                                            "Cancel");

    dialog->setTitle("Save changes");

    dialog->setBody("Save your changes and close the document?");

    dialog->setEmoticonsEnabled(true);

    // Connect the finished() signal to the onDialogFinished() slot.
    // The slot will check the SystemUiResult to see which 
    // button was tapped.

    bool success = connect(dialog,
    	 SIGNAL(finished(bb::system::SystemUiResult::Type)),
    	 this,
    	 SLOT(onDialogFinished(bb::system::SystemUiResult::Type)));

    if (success) {
        // Signal was successfully connected.
	    // Now show the dialog box in your UI.

	    dialog->show();
    } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be a critical
        // situation for your app! Make sure you know exactly why
        // this has happened. Add some code to recover from the 
        // lost connection below this line.
        dialog->deleteLater();
    }
}

void ApplicationUI::onDialogFinished(bb::system::SystemUiResult::Type type)
{
    // do something
}

Cleaning up after a dialog box

Not applicable

If a SystemDialog is created on the heap, it must be destroyed. Because a SystemDialog that's created on the heap must be freed, it is important to remember that the SystemDialog should never be deleted in a slot that handles the finished() signal of the SystemDialog. Instead, if you need to delete a SystemDialog, you should use the deleteLater() function that it inherits from the QObject class. You can see all of these techniques being used in the following sections.

You must create a slot for the finished() signal of the SystemDialog. You can use the deleteLater() function to remove the SystemDialog from the heap when the dialog box is not needed anymore.

For example, you can call deleteLater() in the onDialogFinished() slot that is connected to the finished() signal in the following code sample. The deleteLater() function cleans up the memory that was allocated for the dialog box and its buttons.

#include "applicationui.hpp"

#include <bb/cascades/Application>
#include <bb/cascades/QmlDocument>
#include <bb/cascades/AbstractPane>
#include <bb/cascades/LocaleHandler>
#include <QObject>
#include <bb/cascades/AbstractPane>
#include <bb/system/SystemDialog>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
void ApplicationUI::onDialogFinished(
    bb::system::SystemUiResult::Type type)
{
    // do something
}

You need this slot defined as a public slot in your App.hpp header file as well.

#include <QObject>
#include <bb/system/SystemDialog>
#include <bb/system/SystemUiResult>

// ... 

public:
    ApplicationUI();
    virtual ~ApplicationUI() {}
    Q_INVOKABLE void showDialog();

public slots:
	void onDialogFinished(
        bb::system::SystemUiResult::Type type);

Creating a list dialog box

A list dialog box is a dialog box with a list of choices. The dialog box has a title, a list of choices in the dialog box body, and a set of buttons to accept or cancel the actions on the dialog box. You can create a list dialog box with the following configurations:

If you are creating an app in C++, you can create a SystemListDialog and use the show() slot to display the SystemListDialog in your UI. If you want your UI to block until the user taps a button on your dialog box, you can use the exec() slot to display the SystemListDialog.

See exec() for more information about how to use this function safely in your code.

Selecting a single item in a list

To add an item to the list in the dialog box, you can append it. By default, all items that you add to the list are visible and not selected.

If you are developing a Cascades app, you can use the appendItem() function.

For example, the code sample below creates a list dialog box with a list of Oscar winning movies that looks like the image to the right.

By default, the user can select only one item from the list by tapping anywhere in the list item.

The user can also tap either the confirm or the cancel button without selecting any of the items.

Screen showing a list dialog box with no items selected.

On a device with a physical keyboard, you can see only some of the items in the list. You have to scroll through the list to see all of the items. You should always design your UI so that it is viewable on all BlackBerry devices. For more information, see Device characteristics.

Not available

#include <bb/system/SystemListDialog>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
// A public function to display a SystemListDialog in your UI
void App::showListDialog() 
{

	// Create a SystemListDialog with these characteristics: 
	// The "confirmLabel" (OK button) is set to "My favorite".
	// The "cancelLabel" (CANCEL button) is set to "Cancel".
	// This dialog box doesn't have a custom button.

	SystemListDialog *listdialog = new SystemListDialog("My favorite", 
                                                        "Cancel");

    // Set up the SystemListDialog to allow single selection (default).
	// Add a title and append the selection items.

    listdialog->setTitle("Oscar winning movies");
    listdialog->appendItem("Argo");
    listdialog->appendItem("Amadeus");
    listdialog->appendItem("Braveheart");
    listdialog->appendItem("Casablanca");
    listdialog->appendItem("The Deer Hunter");
    listdialog->appendItem("The English Patient");
    listdialog->appendItem("Driving Miss Daisy");

    // Connect the finished() signal to the onDialogFinished() slot.
    // The slot will check the SystemUiResult to see which button 
    // was tapped.
    bool success = connect(listdialog,
         SIGNAL(finished(bb::system::SystemUiResult::Type)),
         this,
         SLOT(onDialogFinished(bb::system::SystemUiResult::Type)));

    if (success) {
        // Signal was successfully connected.
	    // Now show the dialog box in your UI.

	    listdialog->show();
    } else {
        // Failed to connect to signal.
        // This is not normal in most cases and can be a critical
        // situation for your app! Make sure you know exactly why
        // this has happened. Add some code to recover from the 
        // lost connection below this line.
        
        listdialog->deleteLater();
    }
}

You can add an item to the list, but not allow the user to select it.

If you are developing a Cascades app, you can use the appendItem() function with the enabled parameter set to false.

The code sample below displays a list dialog box that looks like the image to the right. One of the list items is visible but the user can't select it.

Screen showing a SystemListDialog with one item disabled.

Not available

// A public function to display a SystemListDialog in your UI
void App::showListDialog() 
{	
    SystemListDialog *listdialog = new SystemListDialog("My favorite", 
                                                        "Cancel");

    // Set up the SystemListDialog to allow single selection.
	// Add a title and append the selection items.

    listdialog->setTitle("Oscar winning movies");
    listdialog->appendItem("Argo", false);
    listdialog->appendItem("Amadeus");
    listdialog->appendItem("Braveheart");
    listdialog->appendItem("Casablanca");
    listdialog->appendItem("The Deer Hunter");
    listdialog->appendItem("The English Patient");
    listdialog->appendItem("Driving Miss Daisy");

    ...

}

You can also add an item to the list and have it appear selected already. For example, you might want to display a survey with the default response already selected.

If you are developing a Cascades app, you can use the appendItem() function with the enabled parameter and the selected parameter set to true.

The code sample below creates a list dialog box that looks like the image to the right. One of the list items is visible and already selected.

Screen showing a SystemListDialog with one item enabled and selected.

Not available

// A public function to display a SystemListDialog in your UI
void App::showListDialog() 
{	
    SystemListDialog *listdialog = new SystemListDialog("My favorite", 
                                                        "Cancel");

    // Set up the SystemListDialog to allow single selection.
	// Add a title and append the selection items.

    listdialog->setTitle("Oscar winning movies");
    listdialog->appendItem("Argo");
    listdialog->appendItem("Amadeus");
    listdialog->appendItem("Braveheart");
    listdialog->appendItem("Casablanca", true, true);
    listdialog->appendItem("The Deer Hunter");
    listdialog->appendItem("The English Patient");
    listdialog->appendItem("Driving Miss Daisy");

    ...

}

Selecting multiple items in a list

You can also set the selection mode to allow the user to select more than one option from a list. For example, you can create a list dialog box to ask the user to select all the Oscar winning movies that he or she has seen.

The code sample below creates a list dialog box that looks like the image to the right. The user can select multiple items by using check boxes instead of radio buttons for the items.

Screen showing a list dialog box with multiple items selected.

Not available

#include <bb/system/SystemListDialog>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
// A public function to display a SystemListDialog in your UI
void App::showListDialog() 
{
   SystemListDialog *listdialog = 
    new SystemListDialog("I've seen these","Cancel");

   // Set up the SystemListDialog to allow multiple 
   // selections. Add a title and append the selection 
   // items. 
	
   listdialog->setSelectionMode(
        bb::system::ListSelectionMode::Multiple);
   listdialog->setTitle("Oscar winning movies");
   listdialog->appendItem("Argo");
   listdialog->appendItem("Amadeus");
   listdialog->appendItem("Braveheart");
   listdialog->appendItem("Casablanca");
   listdialog->appendItem("The Deer Hunter");
   listdialog->appendItem("The English Patient");
   listdialog->appendItem("Driving Miss Daisy");

   ...

}

Processing the user's selection

See C++

You can use the selectedIndices() function to find out which item the user selected. If the user taps the confirm button or the cancel button without selecting any items in the list, an empty list is returned.

You can call selectedIndices() when the finished() signal is emitted. You can also check to see which button was tapped by using the buttonSelection() function. If the user tapped the cancel button, it might not be valid to look at the list item selections in your app.

You can clear your SystemListDialog using the clearList() function. This function removes all the items from your list, including any formatting that you've added with headers and separators. This technique might be handy to use if you are populating the list dynamically and you want to reset your SystemListDialog.

Creating a progress dialog box

Sometimes you need to show the progress of an activity, such as when your app is saving messages or the device is connecting to a network. A progress dialog box provides the user with an indication of the progress of an activity.

The title of a progress dialog box should reflect the activity that is happening in your app when the dialog box is shown. The text of the body should indicate the progress of the activity.

The optional status message appears below the progress indicator. You can use the status message to give instructions to dismiss the dialog box.

Screen showing a progress dialog box with a definite progress value.

A progress dialog box has a default confirmation button with the default label "OK". You might need to add a confirmation button and a cancelation button, depending on the options that you give the user for this activity. You can retrieve the cancelation button and then give the button a label so that it appears on the progress dialog box.

You can show the progress of the activity. If you set the progress value to a number in the 0-100 range, the user sees the activity indicator shown in the image above.

If you set the progress value to -1, the user sees the indefinite progress indicator shown in the image to the right.

Screen showing a progress dialog box with an indefinite progress value.

Not available

The code sample below creates a SystemProgressDialog with a definite progress value:

#include <bb/system/SystemProgressDialog>
#include <bb/system/SystemUiProgressState>
#include <bb/system/SystemUiResult>

using namespace bb::cascades;
using namespace bb::system;
// A public function to display a 
// SystemProgressDialog in your UI
void App::showProgressDialog() 
{

    // Set up the SystemProgressDialog with a title 
    // and body text. Add an emoticon to the body and
    // enable emoticons.

	SystemProgressDialog *progressdialog 
        = new SystemProgressDialog();

    progressdialog->setTitle("Archiving messages ...");
    progressdialog->setBody("Messages " 
        "have been archived :-)");
    progressdialog->setEmoticonsEnabled(true);

    // Set the progress and ask for the user to 
    // confirm an action.

    progressdialog->setProgress(95);
    progressdialog->
        setStatusMessage("Remove empty chat sessions?");
    progressdialog->setState(SystemUiProgressState::Active);

    // Add a cancel button by setting its label.
    SystemUiButton *button = progressdialog->cancelButton();
    button->setLabel("Cancel");

    // Connect the finished() signal to the onDialogFinished()
    // slot. The slot will check the SystemUiResult to see 
    // which button was tapped.

    bool success = connect(progressdialog,
    	 SIGNAL(finished(bb::system::SystemUiResult::Type)),
    	 this,
    	 SLOT(onDialogFinished(
            bb::system::SystemUiResult::Type)));

    if (success) {
        // Signal was successfully connected.
	    // Now show the dialog box in your UI.

	    progressdialog->show();
    } else {
        // Failed to connect to signal.
        progressdialog->deleteLater();
    }
}

Last modified: 2014-11-17



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

comments powered by Disqus