SystemToast

Since: BlackBerry 10.0.0

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

A system toast

The toast is 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.

When the toast is displayed after a call to show() or exec(), there are two methods for updating the toast after changing its presentation properties.

The default method is to update all the necessary presentation properties and call the update() method. This guarantees that all the presentation properties are updated at the same time.

The second method is to have the toast update automatically after every presentation property change. To enable these automatic updates, the autoUpdateEnabled property must be set to true.

The second method does not guarantee automatic updates for all the presentation properties changes. This method can lead to noticeable delays between updates of individual properties. If more than one property needs to be updated, use the first method. If only one presentation property is being updated frequently (for example, the text on the toast body must be updated to notify the user of the application's current status) the second approach can be used.


Overview

Public Functions Index

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

Public Slots Index

Signals Index

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

Properties

bool autoUpdateEnabled

Indicates whether the toast is updated every time a presentation property is changed.

Note:

The behavior of the autoUpdateEnabled flag is apparent when multiple presentation properties are changed. When autoUpdateEnabled is set to true, the on-screen toast may be updated after each individual presentation property is changed. This may not be an ideal user experience, particularly as the number of changed presentation properties increases. When autoUpdateEnabled is set to false, it is possible to combine multiple presentation property updates and apply them to the on-screen toast as one request by calling show().

Since:

BlackBerry 10.2.0

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

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::SystemUiError::Type error[read-only]

Represents the last error encountered.

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

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

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::SystemUiModality::Type modality

Represents the modality of the toast.

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

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::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 also:

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

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 also:

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

Since:

BlackBerry 10.0.0

Public Functions

SystemToast (

Constructs a new instance of a toast.

Parameters
parent

If not 0, the supplied parent is 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

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

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 is returned. This can occur when the toast timeout expires.

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

The return value is 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

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

Retrieves the error that occurred during the request.

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

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

Return:

The error that occurred.

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

bool isAutoUpdateEnabled ()

Retrieves the flag indicating if the toast is updated every time the value of a presentation property is changed.

Return:

true if the toast automatically updates, false if the toast doesn't update (in which case the show() method must be called after updating the toast presentation properties).

Since:

BlackBerry 10.2.0

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

Retrieves the toast's modality.

See also:

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

Return:

The toast's modality.

Since:

BlackBerry 10.0.0

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

Retrieves the position of the toast.

See also:

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

Return:

The toast position.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetAutoUpdateEnabled ()

Resets the autoUpdateEnabled flag to false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE void resetBody ()

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

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 resetIcon ()

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

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

Q_INVOKABLE void resetPosition ()

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

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 also:

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

Return:

The result of the last completed request.

Since:

BlackBerry 10.0.0

void setAutoUpdateEnabled (
  • boolupdate)

Sets the autoUpdateEnabled flag of the toast.

Parameters
update

true if the toast updates automatically, false if the toast does not update automatically (in which case the show() method must be called after updating the toast presentation properties).

Since:

BlackBerry 10.2.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 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

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

Public Slots

void cancel ()

Cancels the toast if it is still displayed.

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 by using the finished() signal. The button that was selected can be retrieved with the buttonSelection() method.

Unlike show(), this function blocks until a button selection is made or the toast times out. If the toast is already on the screen, this method returns immediately with bb::system::SystemUiResult::DialogCannotBlock.

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 toast 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 show ()

Displays a toast based on current property values.

The result of the request can be retrieved with the SystemToast::result property, or by using the finished() signal. 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

void update ()

Updates an on-screen toast based on the current property values.

If the toast is not on the screen, this method returns immediately and no changes are made to the toast.

Since:

BlackBerry 10.2.0

Signals

void autoUpdateEnabledChanged (
  • boolvalue)

Emitted when the autoUpdateEnabled property is changed programmatically.

Parameters
value

The new value of the autoUpdateEnabled property.

Since:

BlackBerry 10.2.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 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 iconChanged (

Emitted when the icon property is changed programmatically.

Parameters
value

The new value of the icon 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

void positionChanged (

Emitted when the position property is changed programmatically.

Parameters
value

The new value of the position property.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



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

comments powered by Disqus