Toasts

A SystemToast displays a small message that expires and disappears after a predefined amount of time. This message provides users with information and allows them to continue with the application after the toast expires.

A SystemToast uses a dark theme. This approach makes the toast very distinctive on the bright theme, which is the default on an all-touch device. On a dark theme, which is the default on a device with a physical keyboard, you may need to adjust your UI to make sure that toasts are visible on top of your UI. For more information about themes on BlackBerry devices, see Device characteristics.

It is a good practice to keep the body of your toast short. Long toast messages might disappear before the user has a chance to read them.

Creating a system toast in QML

In the code sample that was presented in Creating a system dialog box in QML, a SystemToast was added as an attached object on a Button. When the SystemDialog was displayed, the Cancel button triggered the SystemToast.

The code sample below creates a toast in the Kakel sample app and the image to the right demonstrates the toast on the Kakel UI.

Screen showing a system toast that was added to the Kakel sample app.

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

Creating a system toast in C++

You can also create a toast in C++. You can use the setBody() function to set the body of the toast to a short message. You can use the setIcon() function to add an icon to your toast. The setPosition() function adjusts the positioning of the toast on the screen (MiddleCenter, TopCenter, BottomCenter).

The C++ code sample below creates the toast in the image to the right.

Screen showing a SystemToast on a keyboard device.
void App::showToast() 
{
    SystemToast *toast = new SystemToast(this);

	toast->setBody("Message saved as draft.");
	toast->setPosition(SystemUiPosition::MiddleCenter);
	toast->show();
}

Creating an interactive system toast

So far, you've seen simple toasts that don't need user interaction to be dismissed. The toast appears on top of your UI for a predefined amount of time (the timeout period) and then it disappears automatically.

You can also create a toast that includes a button. If your toast contains a button, it will remain on top of your UI until the user taps the button or touches the UI in any other location. If a toast includes a button and the user taps the button, the toast disappears immediately. If the user touches the screen somewhere other than the button, the timeout period starts and the toast disappears when the timeout period expires.

The image on the right demonstrates a toast with a button. The SystemToast uses a dark theme and is displayed on the dark theme of a device with a physical keyboard. The color of the button text cannot be changed.

Screen showing a Cascades SystemToast with a button.

You may need to adjust your UI to make sure that toasts are visible on top of your UI. For more information about themes on BlackBerry devices, see Device characteristics.

You should use a toast with a button only to allow the user to undo a delete operation. This technique means that you do not need to confirm a delete action. You just need to present a toast to allow the user to recover from an accidental deletion. A button should never be used to add any other interaction to a toast.

You can create a toast that includes a button in QML. Here's a code sample that creates a toast with a button:

import bb.cascades 1.0
import bb.system 1.0

Page {

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

            Container {
                horizontalAlignment: HorizontalAlignment.Center
                verticalAlignment: VerticalAlignment.Center
                
                Button {
                    text: "Create a toast with a button"
                    attachedObjects: [
                        SystemToast {
                            id: myQmlToast
                            body: "Toast has been removed ..."
                            button.label: "Undo"
                            button.enabled: true
                        }	
                    ]
                    onClicked: {
                        myQmlToast.show()
                    }
                } // end of Button
            } // end of Container
        } // end of inner Container
    } // end of top-level Container
} // end of Page

You can create a toast that includes a button in C++. Here's a code sample that creates a toast with a button:

void App::showToastButton() 
{
    SystemToast *toast = new SystemToast();
	SystemUiButton *toastButton = toast->button();

	toast->setBody("Toast has been removed from your food log");
	toastButton->setLabel("Undo");
	toast->show();
}

Creating a progress toast

A SystemProgressToast provides the user with an indication of the progress of an activity. The progress bar gives the user an idea of how long the action will take to complete.

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 progress indicator shown in the image to the right. If you set the progress value to -1, the user will see the indefinite progress indicator.

Screen showing a Cascades SystemProgressToast on a keyboard device.

The code sample below creates a SystemProgressToast in C++. The image to the right shows the SystemProgressToast on a dark theme.

void App::showProgressToast() 
{
    SystemProgressToast *progresstoast = new SystemProgressToast(this);

	progresstoast->setBody("Photo upload");
	progresstoast->setProgress(75);
	progresstoast->setStatusMessage("75% ...");
	progresstoast->setState(SystemUiProgressState::Active);
	progresstoast->setPosition(SystemUiPosition::MiddleCenter);
	progresstoast->show();
}

Last modified: 2013-12-21

comments powered by Disqus