SystemToast

#include <bb/system/SystemToast>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

A message displayed to the user that does not usually require user interaction to be dismissed.

The toast will be dismissed after a predefined timeout period lapses. If the toast includes a button, then the timeout period is activated with the first user interaction, for example, user touching the screen. During this time, if a button is displayed, the user can select it.

Presentation properties are marked as such, and affect future requests. Any pending requests will use the values of the presentation properties at the time of the request.

Note:

To update a toast, call exec() or show() after setting new values for presentation properties.

Since:

BlackBerry 10.0.0

Public Functions Index

SystemToast (QObject *parent=0)
virtual ~SystemToast ()
QStringbody () const
QUrlicon () const
bb::system::SystemUiPosition::Typeposition () const
SystemUiButton *button ()
bb::system::SystemUiModality::Typemodality () const
voidsetBody (const QString &body)
voidsetIcon (const QUrl &icon)
voidsetPosition (bb::system::SystemUiPosition::Type newPosition)
voidsetModality (bb::system::SystemUiModality::Type newModality)
Q_INVOKABLE voidresetBody ()
Q_INVOKABLE voidresetIcon ()
Q_INVOKABLE voidresetPosition ()
Q_INVOKABLE voidresetButton ()
Q_INVOKABLE voidresetModality ()
bb::system::SystemUiResult::Typeresult () const
bb::system::SystemUiError::Typeerror () const
Q_INVOKABLE bb::system::SystemUiButton *buttonSelection () const

Public Slots Index

voidshow ()
bb::system::SystemUiResult::Typeexec ()
voidcancel ()

Signals Index

voidfinished (bb::system::SystemUiResult::Type value)
voidbodyChanged (const QString &value)
voidiconChanged (const QUrl &value)
voidpositionChanged (bb::system::SystemUiPosition::Type value)
voidmodalityChanged (bb::system::SystemUiModality::Type newModality)

Properties

QString body

Represents the main text of the toast.

This is a presentation property whose default value is a default-constructed QString.

Since:

BlackBerry 10.0.0

QUrl icon

Represents the path to an image file that can be included in the toast.

This is a presentation property whose default value is a default-constructed QUrl.

Since:

BlackBerry 10.0.0

bb::system::SystemUiPosition::Type position

Represents the position of the toast on the display.

This is a presentation property whose default value is bb::system::SystemUiPosition::MiddleCenter.
See:

bb::system::SystemUiPosition for a list of possible values.

Since:

BlackBerry 10.0.0

bb::system::SystemUiModality::Type modality

Represents the modality of the toast.

This is a presentation property whose value is bb::system::SystemUiModality::Application.
See:

bb::system::SystemUiModality for the list of valid values.

Note:

Toasts are non-modal. Modality refers to the scope of the toast.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton button[read-only]

Represents the button that can be included in the toast.

This is a presentation property whose default bb::system::SystemUiButton::label property is a default-constructed QString.

Note:

The button is always shown as enabled. This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type result[read-only]

Represents the result of the last completed request.

To obtain result values once the request is finished, use the following functions:

  • result() - the result of the request

  • error() - the error that occurred during the request (if applicable)

  • buttonSelection() - the button selected (if applicable)

See:

bb::system::SystemUiResult for the list of possible results.

Since:

BlackBerry 10.0.0

bb::system::SystemUiError::Type error[read-only]

Represents the last error encountered.

This property is only valid when SystemToast::result is bb::system::SystemUiResult::Error.
See:

bb::system::SystemUiError for the list of possible errors.

Since:

BlackBerry 10.0.0

Public Functions

SystemToast (

Constructs a new instance of a toast.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.
Since:

BlackBerry 10.0.0

virtual~SystemToast ()

Destructor.

Since:

BlackBerry 10.0.0

QString body ()

Retrieves the main text of the toast.

Return:

The text of the toast.

Since:

BlackBerry 10.0.0

QUrl icon ()

Retrieves the icon for the toast.

Return:

The local path to the icon for the toast.

Since:

BlackBerry 10.0.0

bb::system::SystemUiPosition::Type position ()

Retrieves the position of the toast.

See:

bb::system::SystemUiPosition for the list of valid positions.

Return:

The toast position.

Since:

BlackBerry 10.0.0

SystemUiButton * button ()

Retrieves the toast's button.

This instance retains ownership of the returned value.
Return:

The toast's button.

Since:

BlackBerry 10.0.0

bb::system::SystemUiModality::Type modality ()

Retrieves the toast's modality.

See:

bb::system::SystemUiModality for the list of possible values.

Return:

The toast's modality.

Since:

BlackBerry 10.0.0

void setBody (

Sets the main text of the toast.

Parameters
body

The new text of the toast.
Since:

BlackBerry 10.0.0

void setIcon (

Sets the icon for the toast.

Parameters
icon

The new local path to the icon for the toast.
Since:

BlackBerry 10.0.0

void setPosition (

Sets the position of the toast.

Parameters
newPosition

The new toast position. See bb::system::SystemUiPosition for the list of valid positions.
Since:

BlackBerry 10.0.0

void setModality (

Sets the modality for the toast.

Parameters
newModality

The new modality preference. See bb::system::SystemUiModality for the list of possible values.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetBody ()

Resets the main text of the toast to QString::null.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetIcon ()

Resets the icon URL for the toast to an empty, default-constructed QUrl.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetPosition ()

Resets the position of the toast to bb::system::SystemUiPosition::MiddleCenter.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetButton ()

Resets the button for this toast to be a default button with no text.

A reset button will not be shown.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetModality ()

Resets the modality of the toast to bb::system::SystemUiModality::Application.

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type result ()

Retrieves the result of the last completed request.

If no request has been made, or if a request is pending, bb::system::SystemUiResult::None is returned.
See:

bb::system::SystemUiResult for the list of possible results.

Return:

The result of the last completed request.

Since:

BlackBerry 10.0.0

bb::system::SystemUiError::Type error ()

Retrieves the error that occurred during the request.

The return value will be reset when a new request is made.
See:

bb::system::SystemUiError for the list of possible errors.

Return:

The error that occurred.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::system::SystemUiButton * buttonSelection ()

Returns the button that was selected when a button selection is made.

If no button has been selected, 0 will be returned. This can occur when the toast timeout expires.

This function will return the result of the button selection of show() and exec().

The return value will be reset when a new request is made.

This instance retains ownership of the returned value.
Return:

The button selected by the user.

Since:

BlackBerry 10.0.0

Public Slots

void show ()

Displays or updates the toast based on current property values.

The result of the request can be retrieved with the SystemToast::result property, or using the signal finished(). The button that was selected can be retrieved with the buttonSelection() method.

Control is returned to the caller immediately. For a blocking request, use exec().

Since:

BlackBerry 10.0.0

bb::system::SystemUiResult::Type exec ()

Displays or updates the toast based on current property values.

The result of the request can be retrieved using the SystemToast::result property, or using the signal finished(). The button that was selected can be retrieved with the buttonSelection() method.

Unlike show(), this function will block until a button selection is made or the toast times out.

Note:
Blocking occurs by starting a nested QEventLoop. To use this method safely, the following conditions must be met:

  • Any connections to this slot must use a Qt::QueuedConnection, or the slot must be triggered using QTimer::singleShot(), and

  • QObject::deleteLater() must be used in place of delete when deleting the dialog object. If these conditions are not met, unexpected behavior may result.

Return:

The result of the request. See bb::system::SystemUiResult for the list of possible results.

Since:

BlackBerry 10.0.0

void cancel ()

Cancels the toast if it is still displayed.

Since:

BlackBerry 10.0.0

Signals

void finished (

Emitted when a request is completed.

The button selection can be retrieved with buttonSelection().
Parameters
value

The result of the request. See bb::system::SystemUiResult for the list of possible results.
Since:

BlackBerry 10.0.0

void bodyChanged (

Emitted when the body property is changed programmatically.

Parameters
value

The new value of the body property.
Since:

BlackBerry 10.0.0

void iconChanged (

Emitted when the icon property is changed programmatically.

Parameters
value

The new value of the icon property.
Since:

BlackBerry 10.0.0

void positionChanged (

Emitted when the position property is changed programmatically.

Parameters
value

The new value of the position property.
Since:

BlackBerry 10.0.0

void modalityChanged (

Emitted when the modality property is changed programmatically.

Parameters
newModality

The new value of the modality property.
Since:

BlackBerry 10.0.0