Toasts

A system toast 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 system toast uses a dark theme. This approach makes the toast 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 toast

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

In the code sample that was presented in Creating a dialog box, a SystemToast was added as an attached object on a Button.

When the SystemDialog was displayed, the Cancel button triggered the SystemToast.

Screen showing a toast that was added in QML.
import bb.cascades 1.0
import bb.system 1.0
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: "Games can be habit-forming... "
          onFinished: {
               if (myQmlDialog.result 
                   == SystemUiResult.CancelButtonSelection) 
               	myQmlToast.show();
          }
       }
    ]
    onClicked: {
        myQmlDialog.show()
    }
} // button

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

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).

Screen showing a toast on a device with a physical keyboard.
#include <bb/system/SystemToast>
#include <bb/system/SystemUiPosition>

using namespace bb::cascades;
using namespace bb::system;
void App::showToast() 
{
    SystemToast *toast = new SystemToast(this);

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

Creating an interactive 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 default 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 remains 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.

Screen showing a toast with a button.

The image above demonstrates a toast with a button. The toast 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.

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 don't need to confirm a deletion. You need to present a toast only to allow the user to recover from an accidental deletion. A button should never be used to add any other interaction to a toast.

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
                
                // Create a simple toast with a button

                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
#include <bb/system/SystemToast>
#include <bb/system/SystemUiButton>

using namespace bb::cascades;
using namespace bb::system;
void App::showToastButton() 
{
   // Create a simple toast with a button

   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 progress toast 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 takes to complete.

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

Screen showing a progress toast on a device with a physical keyboard.

The code samples below creates a progress toast. The image above shows the progress toast on a dark theme.

Not available

#include <bb/system/SystemProgressToast>
#include <bb/system/SystemUiProgressState>
#include <bb/system/SystemUiPosition>

using namespace bb::cascades;
using namespace bb::system;
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: 2014-11-17



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

comments powered by Disqus