System dialog boxes

A SystemDialog is a dialog box that is standardized across all applications. These dialog boxes have a predefined look and feel for BlackBerry 10.

All SystemDialog objects have similar properties. 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.

Screen showing a system dialog box.

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.

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 direct a SystemDialog to disappear automatically by using the dismissAutomatically property. Using the dismissAutomatically property doesn't release the SystemDialog from memory.

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'll see all of these techniques being used in the following sections.

Prerequisites

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

LIBS += -lbbsystem

To use SystemDialog classes in QML, you must import the bb.system library in your QML file.

import bb.system 1.0

To use SystemDialog classes in C++, you must include the bb::system classes in your app header file. It's also a good idea to use the bb::system namespace so that you don't have to use fully qualified names in your code.

#include <QObject>
#include <bb/cascades/AbstractPane>
#include <bb/system/SystemDialog>
#include <bb/system/SystemListDialog>
#include <bb/system/SystemProgressDialog>
#include <bb/system/SystemPrompt>
#include <bb/system/SystemCredentialsPrompt>
#include <bb/system/SystemToast>
#include <bb/system/SystemProgressToast>
#include <bb/system/SystemUiButton>
#include <bb/system/SystemUiInputField>
#include <bb/system/SystemUiError>
#include <bb/system/SystemUiInputMode>
#include <bb/system/SystemUiModality>
#include <bb/system/SystemUiPosition>
#include <bb/system/SystemUiProgressState>
#include <bb/system/SystemUiResult>
#include <bb/system/SystemUiReturnKeyAction>

using namespace bb::system;

Exploring system dialog properties

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.

SystemDialog objects have the following basic properties:

title

This property is the title that's displayed at the top of the dialog box. The title of your dialog box is only one line. Any characters that extend beyond the end of the title on the dialog box will be truncated.

body

This property is the main text of the dialog box. You have lots of room to provide information, but you should take into account different device types to make sure that the body of your dialog box is viewable on every device. For more information about BlackBerry device types, see Device characteristics.

emoticonsEnabled

This property lets you specify whether you want to display emoticons in the body of your dialog box. By default, this property is false.

dismissAutomatically

This Boolean value indicates whether the dialog box should be dismissed when a button is tapped. If you set this to false, you must dismiss the dialog box with cancel() in your app. By default, this property is true.

returnKeyAction

This property specifies the action you want to associate with the Return key. By default, the Return key dismisses the dialog box. You can specify an alternate action by using the SystemUiReturnKeyAction class.

modality

This property specifies the modality setting (either Application or Global). In general, dialog boxes should use the default value, Application, for modality. Setting the modality to Global will cause your dialog box to interrupt the UI flow of all applications. This practice is not recommended. For more information, see SystemUiModality.

confirmButton

This property lets you specify the OK button. When the user taps this button, the finished() signal is emitted. You can omit this button by setting its label to QString::null.

cancelButton

This property lets you specify the Cancel button. When the user taps this button, the finished() signal is emitted. You can omit this button by setting its label to QString::null.

result

This property represents the result of the last dialog box action. For more information, see SystemUiResult.

error

This property gives you the most recent error that occurred with your dialog box. For more information, see SystemUiError.

You can add other buttons to a SystemDialog by calling appendButton() with a SystemUiButton. This function accepts a SystemUiButton object and adds it as a button to the dialog box. When the button is tapped, the SystemDialog emits the finished() signal and returns CustomButtonSelection in the SystemUiResult.

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

You can use the following properties to customize the buttons on your dialog box:

customButton

This property lets you specify an optional custom button to include in the dialog box. This button is represented by a SystemUiButton object.

defaultButton

This property represents the button associated with the Return key action of the window.

buttonAreaLimit

This property represents the number of buttons you want to show in the button area of the window. Typically, between one and three buttons are used, because the cancelButton and the customButton are optional. Any additional buttons are placed in the content area of the SystemDialog.

buttons

This property represents buttons that appear in the SystemDialog window (not in the button area). They can be added as SystemUiButton objects.

You can use the following properties to add an option to your dialog to remember the user's input:

includeRememberMe

This property indicates whether a Remember me check box should be included in the dialog box.

rememberMeChecked

This property represents the state of the Remember me check box (checked or unchecked).

rememberMeText

This property represents the text to associate with the Remember me check box.

Creating a system dialog box in QML

You can create a SystemDialog using QML. Before you can create a SystemDialog in QML, you must import the bb.system 1.0 library in your main.qml file.

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.

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.

Screen showing a system dialog box created in QML.
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

Creating a system dialog box in C++

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.

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

Screen showing a system dialog box on a keyboard device.
// 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();
    }
}

You must create a slot for the finished() signal. You'll need this slot defined as a public slot in your App.hpp header as well.

public:
    App();

    Q_INVOKABLE void showDialog();

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

You can use the deleteLater() function to remove the SystemDialog from the heap after 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 code sample above. The deleteLater() function cleans up the memory that was allocated for the dialog box and its buttons.

Creating a list dialog box

A SystemListDialog 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 SystemListDialog with the following configurations:

  • Default OK and Cancel buttons
  • Only a confirmation button
  • A confirmation button and cancel button
  • A confirmation button, cancel button, and custom button

For more information, see the API reference documentation for the SystemListDialog constructors.

You can create a SystemListDialog in C++ 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 in your UI.

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

Allowing the user to select a single item from a list

To add an item to the list in the dialog box, you can use the appendItem() function. By default, all items that you add to the list are visible and unselected.

For example, the code sample below creates a SystemListDialog 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 SystemListDialog with no items selected.

On a device with a physical keyboard, you'll notice that you can see only five 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.

// 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();
    }
}

To add an item to the list, but not allow the user to select it, you can use the appendItem() function with the enabled parameter set to false.

The code sample below displays a SystemListDialog 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.
// 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 already selected using the appendItem() function. This function takes an enabled parameter and a selected parameter. Perhaps you want to display a survey with the default response already selected.

The code sample below creates a SystemListDialog 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.
// 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");

    ...

}

Allowing the user to select multiple items in the list

You can also set the selectionMode property, which uses values from the ListSelectionMode enumeration, to allow the user to select more than one option from a list. You can use this property to ask the user to select all the Oscar winning movies that he or she has seen.

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

Screen showing a SystemListDialog with multiple items selected.
// 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

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 SystemProgressDialog provides the user with an indication of the progress of an activity.

The title of a SystemProgressDialog 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 statusMessage appears below the progress indicator. You can use the statusMessage to give instructions to dismiss the dialog box.

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

You'll notice that there is a default confirmButton with the default label "OK". You might need to add a confirmButton and a cancelButton, depending on the options that you give the user for this activity. You can retrieve the cancelButton by using the cancelButton() function. Then you can use the setlabel() function to give the button a label so that it will appear on the progress dialog box.

You can use the setProgress() function to show the progress of the activity. If you set the progress value to a number in the 0-100 range, the user will see the activity indicator shown in the image above.

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

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

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

// 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("Your messages " 
        "have been successfully 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.
        // 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.
        
        progressdialog->deleteLater();
    }
}

Last modified: 2014-05-14



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

comments powered by Disqus