SystemProgressToast

Since: BlackBerry 10.0.0

#include <bb/system/SystemProgressToast>

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

A message displayed to the user that presents the progress of a task and does not usually require user interaction to be dismissed.

A system progress toast

The toast is dismissed after a predefined timeout period expires. 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 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

SystemProgressToast (QObject *parent=0)
virtual ~SystemProgressToast ()
QStringbody () const
bb::system::SystemUiButton *button ()
Q_INVOKABLE bb::system::SystemUiButton *buttonSelection () const
bb::system::SystemUiError::Typeerror () const
boolisAutoUpdateEnabled () const
bb::system::SystemUiModality::Typemodality () const
bb::system::SystemUiPosition::Typeposition () const
intprogress () const
Q_INVOKABLE voidresetAutoUpdateEnabled ()
Q_INVOKABLE voidresetBody ()
Q_INVOKABLE voidresetButton ()
Q_INVOKABLE voidresetModality ()
Q_INVOKABLE voidresetPosition ()
Q_INVOKABLE voidresetProgress ()
Q_INVOKABLE voidresetState ()
Q_INVOKABLE voidresetStatusMessage ()
bb::system::SystemUiResult::Typeresult () const
voidsetAutoUpdateEnabled (bool update)
voidsetBody (const QString &body)
voidsetModality (bb::system::SystemUiModality::Type newModality)
voidsetPosition (bb::system::SystemUiPosition::Type pos)
voidsetProgress (int newProgress)
voidsetState (bb::system::SystemUiProgressState::Type newProgressState)
voidsetStatusMessage (const QString &newStatusMessage)
bb::system::SystemUiProgressState::Typestate () const
QStringstatusMessage () const

Public Slots Index

Signals Index

voidautoUpdateEnabledChanged (bool value)
voidbodyChanged (const QString &value)
voidfinished (bb::system::SystemUiResult::Type value)
voidmodalityChanged (bb::system::SystemUiModality::Type newModality)
voidpositionChanged (bb::system::SystemUiPosition::Type value)
voidprogressChanged (int newProgress)
voidstateChanged (bb::system::SystemUiProgressState::Type newState)
voidstatusMessageChanged (const QString &newStatusMessage)

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 result is bb::system::SystemUiResult::Error.

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

int progress

Represents the progress of the task represented by the toast.

The range of values is [0-100], and -1 represents indefinite progress.

This is a presentation property whose default value is -1.

Since:

BlackBerry 10.0.0

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

Represents the result of the last completed request.

To obtain result values when 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

bb::system::SystemUiProgressState::Type state

Represents the state of the task whose progress is represented by the toast.

This is a presentation property whose default value is bb::system::SystemUiProgressState::Active.
See also:

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

Since:

BlackBerry 10.0.0

QString statusMessage

Represents the status message of the toast.

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

Note:

This property is ignored if progress is indefinite, that is, -1.

Since:

BlackBerry 10.0.0

Public Functions

SystemProgressToast (

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~SystemProgressToast ()

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

bb::system::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.

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.
Return:

The error that occurred.

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.

Return:

The toast's modality.

Since:

BlackBerry 10.0.0

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

Retrieves the position of the toast.

Return:

The toast position.

Since:

BlackBerry 10.0.0

int progress ()

Retrieves the progress of the toast.

The value is in the range [0-100] for definite progress, and -1 for indefinite progress.
Return:

The progress of the toast.

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 is not 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

Q_INVOKABLE void resetPosition ()

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

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetProgress ()

Resets the progress of the toast to -1.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetState ()

Resets the progress state of the toast to bb::system::SystemUiProgressState::Active.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetStatusMessage ()

Resets the progress status message of the toast to QString::null.

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.
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 text of the toast.

Since:

BlackBerry 10.0.0

void setModality (

Sets the modality for the toast.

Parameters
newModality

The new modality preference.

Since:

BlackBerry 10.0.0

void setPosition (

Sets the position of the toast.

Parameters
pos

The toast position.

Since:

BlackBerry 10.0.0

void setProgress (
  • intnewProgress)

Sets the progress of the toast.

The range for definite progress is [0-100], and indefinite progress is -1. Values beyond that range are set to -1.
Parameters
newProgress

The progress of the toast.

Since:

BlackBerry 10.0.0

void setState (

Sets the state of progress of the toast.

Parameters
newProgressState

The progress state of the toast.

Since:

BlackBerry 10.0.0

void setStatusMessage (

Sets the status message for the progress of the task represented by the toast.

Parameters
newStatusMessage

The status message of the progress of the toast.

Since:

BlackBerry 10.0.0

bb::system::SystemUiProgressState::Type state ()

Retrieves the state of the progress of the task represented by the toast.

Return:

The progress state.

Since:

BlackBerry 10.0.0

QString statusMessage ()

Retrieves the status message of the progress of the toast.

Return:

The status message of the toast.

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

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.

Since:

BlackBerry 10.0.0

void show ()

Displays a toast based on current property values.

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

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

void progressChanged (
  • intnewProgress)

Emitted when the progress property is changed programmatically.

Parameters
newProgress

The new value of the progress property.

Since:

BlackBerry 10.0.0

void stateChanged (

Emitted when the state property is changed programmatically.

Parameters
newState

The new value of the state property.

Since:

BlackBerry 10.0.0

void statusMessageChanged (

Emitted when the statusMessage property is changed programmatically.

Parameters
newStatusMessage

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