SystemProgressToast

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

The toast will be 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 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

SystemProgressToast (QObject *parent=0)
virtual ~SystemProgressToast ()
QStringbody () const
intprogress () const
QStringstatusMessage () const
bb::system::SystemUiProgressState::Typestate () const
bb::system::SystemUiPosition::Typeposition () const
SystemUiButton *button ()
bb::system::SystemUiModality::Typemodality () const
voidsetBody (const QString &body)
voidsetProgress (int newProgress)
voidsetStatusMessage (const QString &newStatusMessage)
voidsetState (bb::system::SystemUiProgressState::Type newProgressState)
voidsetPosition (bb::system::SystemUiPosition::Type pos)
voidsetModality (bb::system::SystemUiModality::Type newModality)
Q_INVOKABLE voidresetBody ()
Q_INVOKABLE voidresetProgress ()
Q_INVOKABLE voidresetStatusMessage ()
Q_INVOKABLE voidresetState ()
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)
voidprogressChanged (int newProgress)
voidstatusMessageChanged (const QString &newStatusMessage)
voidstateChanged (bb::system::SystemUiProgressState::Type newState)
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

int progress

Represents the progress of the task represented by the toast.

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

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

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 will be ignored if progress is indefinite, that is, -1.

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:

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

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

Since:

BlackBerry 10.0.0

Public Functions

SystemProgressToast (

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

int progress ()

Retrieves the progress of the toast.

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

The progress of the toast.

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

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

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

Retrieves the position of the toast.

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.

Return:

The toast's modality.

Since:

BlackBerry 10.0.0

void setBody (

Sets the main text of the toast.

Parameters
body

The text of the toast.
Since:

BlackBerry 10.0.0

void setProgress (
  • intnewProgress)

Sets the progress of the toast.

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

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

void setState (

Sets the state of progress of the toast.

Parameters
newProgressState

The progress state of the toast.
Since:

BlackBerry 10.0.0

void setPosition (

Sets the position of the toast.

Parameters
pos

The toast position.
Since:

BlackBerry 10.0.0

void setModality (

Sets the modality for the toast.

Parameters
newModality

The new modality preference.
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 resetProgress ()

Resets the progress of the toast to -1.

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

Q_INVOKABLE void resetState ()

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

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

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 result, or using the signal finished. 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

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

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.

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

Emitted when the statusMessage property is changed programmatically.

Parameters
newStatusMessage

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