SystemProgressDialog

Since: BlackBerry 10.0.0

#include <bb/system/SystemProgressDialog>

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

A dialog box that presents the user with a list of buttons and the progress of a task.

A system progress dialog

The dialog box displayed is an application modal window, though it is possible to use a system modal window by setting modality. The dialog box allows for text to be contained in its content area.

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 dialog box is displayed after a call to show() or exec(), there are two methods for updating the dialog box 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 dialog box 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 dialog box body must be updated to notify the user of the application's current status) the second approach can be used.


Overview

Public Functions Index

SystemProgressDialog (QObject *parent=0)
SystemProgressDialog (const QString &confirmLabel, QObject *parent=0)
virtual ~SystemProgressDialog ()
boolactivityIndicatorVisible () const
QStringbody () const
intbuttonAreaLimit () const
Q_INVOKABLE bb::system::SystemUiButton *buttonSelection () const
bb::system::SystemUiButton *cancelButton ()
bb::system::SystemUiButton *confirmButton ()
bb::system::SystemUiButton *customButton ()
bb::system::SystemUiButton *defaultButton ()
booldismissAutomatically () const
boolemoticonsEnabled () const
bb::system::SystemUiError::Typeerror () const
QUrlicon () const
boolincludeRememberMe () const
boolisAutoUpdateEnabled () const
bb::system::SystemUiModality::Typemodality () const
intprogress () const
boolrememberMeChecked () const
Q_INVOKABLE boolrememberMeSelection () const
QStringrememberMeText () const
Q_INVOKABLE voidresetActivityIndicatorVisible ()
Q_INVOKABLE voidresetAutoUpdateEnabled ()
Q_INVOKABLE voidresetBody ()
Q_INVOKABLE voidresetButtonAreaLimit ()
Q_INVOKABLE voidresetCancelButton ()
Q_INVOKABLE voidresetConfirmButton ()
Q_INVOKABLE voidresetCustomButton ()
Q_INVOKABLE voidresetDefaultButton ()
Q_INVOKABLE voidresetDismissAutomatically ()
Q_INVOKABLE voidresetEmoticonsEnabled ()
Q_INVOKABLE voidresetIcon ()
Q_INVOKABLE voidresetIncludeRememberMe ()
Q_INVOKABLE voidresetModality ()
Q_INVOKABLE voidresetProgress ()
Q_INVOKABLE voidresetRememberMeChecked ()
Q_INVOKABLE voidresetRememberMeText ()
Q_INVOKABLE voidresetReturnKeyAction ()
Q_INVOKABLE voidresetState ()
Q_INVOKABLE voidresetStatusDetails ()
Q_INVOKABLE voidresetStatusMessage ()
Q_INVOKABLE voidresetTitle ()
bb::system::SystemUiResult::Typeresult () const
bb::system::SystemUiReturnKeyAction::TypereturnKeyAction () const
voidsetActivityIndicatorVisible (bool visible)
voidsetAutoUpdateEnabled (bool update)
voidsetBody (const QString &body)
voidsetButtonAreaLimit (int newButtonAreaLimit)
voidsetDefaultButton (bb::system::SystemUiButton *newDefaultButton)
voidsetDismissAutomatically (bool automaticDismissal)
voidsetEmoticonsEnabled (bool newEmoticonsEnabled)
voidsetIcon (const QUrl &icon)
voidsetIncludeRememberMe (bool value)
voidsetModality (bb::system::SystemUiModality::Type newModality)
voidsetProgress (int newProgress)
voidsetRememberMeChecked (bool newRememberMeSelected)
voidsetRememberMeText (const QString &newRememberMeText)
voidsetReturnKeyAction (bb::system::SystemUiReturnKeyAction::Type newReturnKeyAction)
voidsetState (bb::system::SystemUiProgressState::Type newProgressState)
voidsetStatusDetails (const QString &newStatusDetails)
voidsetStatusMessage (const QString &newStatusMessage)
voidsetTitle (const QString &title)
bb::system::SystemUiProgressState::Typestate () const
QStringstatusDetails () const
QStringstatusMessage () const
QStringtitle () const

Public Slots Index

Signals Index

voidactivityIndicatorVisibleChanged (bool value)
voidautoUpdateEnabledChanged (bool value)
voidbodyChanged (const QString &value)
voidbuttonAreaLimitChanged (int newButtonAreaLimit)
voiddefaultButtonChanged (bb::system::SystemUiButton *newDefaultButton)
voiddismissAutomaticallyChanged (bool automaticDismissal)
voidemoticonsEnabledChanged (bool newEmoticonsEnabled)
voidfinished (bb::system::SystemUiResult::Type value)
voidiconChanged (const QUrl &value)
voidincludeRememberMeChanged (bool value)
voidmodalityChanged (bb::system::SystemUiModality::Type newModality)
voidprogressChanged (int newProgress)
voidrememberMeCheckedChanged (bool newRememberMeSelected)
voidrememberMeTextChanged (const QString &newRememberMeText)
voidreturnKeyActionChanged (bb::system::SystemUiReturnKeyAction::Type newReturnKeyAction)
voidstateChanged (bb::system::SystemUiProgressState::Type newState)
voidstatusDetailsChanged (const QString &newStatusDetails)
voidstatusMessageChanged (const QString &newStatusMessage)
voidtitleChanged (const QString &value)

Properties

bool activityIndicatorVisible

Indicates whether to display an activity indicator in the title bar of the dialog box.

Note:

When the dialog box is shown for the first time, this property is ignored. The visibility of the activity indicator depends on the value of progress. On subsequent updates of the dialog box, if the value of progress is not -1 activityIndicatorVisible can be used to control the visibility of the activity indicator in the title bar of the dialog box.

Since:

BlackBerry 10.2.0

bool autoUpdateEnabled

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

If autoUpdateEnabled is true, every time any of the presentation properties on the dialog box are changed, the dialog box is also update immediately to reflect the changes on the UI. If autoUpdateEnabled is false, the dialog box is not updated automatically, instead the show() method must be called. This is the default behavior.

Note:

The behavior of the autoUpdateEnabled flag is apparent when multiple presentation properties are changed. When autoUpdateEnabled is set to true, the on-screen dialog box 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 dialog box as one request by calling show().

Since:

BlackBerry 10.2.0

QString body

Represents the main text of the window.

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

Since:

BlackBerry 10.0.0

int buttonAreaLimit

The maximum number of buttons that can be shown without causing an overflow.

When overflow occurs, all buttons are stacked vertically.

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

-1 implies that the default system behavior is applied. The supported range is 1-3, with any values outside the range resetting the property to its default value.

Since:

BlackBerry 10.0.0

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

Represents the button associated with the default cancellation action of the dialog box.

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

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

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

Represents the button associated with the default confirming action of the dialog box.

This is a presentation property whose default bb::system::SystemUiButton::label property is "OK".

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

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

Represents the button associated with the tertiary action of the dialog box.

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

Note:

This button is omitted if its bb::system::SystemUiButton::label property is a default-constructed QString.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton defaultButton

Represents the button associated with the return key action of the dialog box.

When the user triggers the return key action, this button is automatically selected. If the defaultButton is NULL, then triggering the return key action will not select any button.

If defaultButton is set to a button that this instance does not manage, then this property is undefined.

This is a presentation property whose default value is determined dynamically based on which managed buttons are available. The precedence of the buttons is as follows:
  • confirmButton

  • cancelButton

  • customButton

Since:

BlackBerry 10.0.0

bool dismissAutomatically

Indicates whether to dismiss the dialog box when a button is selected.

If false, the dialog box must be dismissed using cancel(). Otherwise, the dialog box is dismissed when a button is selected.

This is a presentation property whose default value is true.

Since:

BlackBerry 10.0.0

bool emoticonsEnabled

Retrieves whether the text can be displayed with emoticons.

This is a presentation property whose default value is false.

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

QUrl icon

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

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

Since:

BlackBerry 10.0.0

bool includeRememberMe

Indicates whether a check box for remembering user selection should be included in the dialog box.

If a check box is requested, then the user will have the ability to enable and disable it. The user selection is available via rememberMeSelection() when the request is finished. To customize how the check box is presented, use rememberMeChecked() and rememberMeText().

This is a presentation property whose default value is false.

Since:

BlackBerry 10.0.0

bb::system::SystemUiModality::Type modality

Represents the modality of the dialog box.

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

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

Since:

BlackBerry 10.0.0

int progress

Represents the progress of the task presented in the dialog box.

The range of values is [0-100]. A value of -1 is used to represent indefinite progress, which will cause the dialog box to display an activity indicator in the title bar of the dialog box instead of a progress bar.

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

Since:

BlackBerry 10.0.0

bool rememberMeChecked

Represents the selection state of the check box for remembering user selection.

The state is only applied if includeRememberMe is true. To obtain the user selection for this property when the request is finished, use rememberMeSelection().

This is a presentation property whose default value is true.

Since:

BlackBerry 10.0.0

QString rememberMeText

Represents the text to associate with the check box associated with rememberMeChecked.

This property is only applied if includeRememberMe is true.

This is a presentation property whose default value is "Remember Me".

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

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

Since:

BlackBerry 10.0.0

bb::system::SystemUiReturnKeyAction::Type returnKeyAction

Represents the action associated with the return key for this dialog box.

This is a presentation property whose default value is bb::system::SystemUiReturnKeyAction::Default.
See also:

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

Since:

BlackBerry 10.0.0

bb::system::SystemUiProgressState::Type state

Represents the state of the task whose progress is represented by the dialog box.

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 statusDetails

Provides additional information regarding the progress of the task of the dialog box.

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

QString statusMessage

Provides the status message regarding the progress of the task of the dialog box.

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

QString title

Represents the title of the window.

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

Since:

BlackBerry 10.0.0

Public Functions

SystemProgressDialog (

Constructs a new instance of a dialog box with a defined confirmation button.

The confirmation button will have default label "OK".
Parameters
parent

If not 0, the supplied parent is responsible for deleting this instance.

Since:

BlackBerry 10.0.0

SystemProgressDialog (

Constructs a new instance of a dialog box with only a confirmation button.

To show the cancellation and custom button set the labels of cancelButton and customButton respectively.
Parameters
confirmLabel

The label to use for confirmButton.

parent

If not 0, the supplied parent is responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~SystemProgressDialog ()

Destructor.

Since:

BlackBerry 10.0.0

bool activityIndicatorVisible ()

Indicates if an activity indicator is displayed on the title bar of the dialog box.

Return:

true if the activity indicator is displayed, false otherwise.

Since:

BlackBerry 10.2.0

QString body ()

Retrieves the main text of the dialog box.

Return:

The text of the dialog box.

Since:

BlackBerry 10.0.0

int buttonAreaLimit ()

The maximum number of buttons that can be shown without causing an overflow.

If buttonAreaLimit is larger than the number of buttons that will be displayed, all buttons are stacked vertically.
Return:

The limit for the number of buttons that can be accommodated in the button area, or -1 if system defaults should be used.

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 function will return 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::SystemUiButton * cancelButton ()

Retrieves the button attached to the dialog box's cancel button.

This instance retains ownership of the returned value.
Return:

The dialog box's cancel button.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton * confirmButton ()

Retrieves the button attached to the dialog box's confirm button.

This instance retains ownership of the returned value.
Return:

The dialog box's confirm button.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton * customButton ()

Retrieves the button attached to the dialog box's custom action button.

This instance retains ownership of the returned value.
Return:

The dialog box's custom action button.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton * defaultButton ()

Retrieves the dialog box's default button.

This instance retains ownership of the returned value.

The default button is automatically selected when the user triggers the return key action. If the default button is NULL, no button will be automatically selected.

The returned value is one of the buttons managed by this instance, or NULL.
Return:

The dialog box's default button.

Since:

BlackBerry 10.0.0

bool dismissAutomatically ()

Retrieves whether the dialog box is dismissed when a button is selected.

Return:

true if selecting a button dismisses the dialog box, false otherwise.

Since:

BlackBerry 10.0.0

bool emoticonsEnabled ()

Retrieves whether the text can be displayed as emoticons.

Return:

Whether the dialog box supports emoticons.

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

QUrl icon ()

Retrieves the icon for the dialog box.

Return:

The local path to the icon for the dialog box.

Since:

BlackBerry 10.0.0

bool includeRememberMe ()

Retrieves the flag indicating if a check box to remember user selection should be included in the dialog box.

Return:

true if a check box for remembering the user selection should be included in the dialog box, false otherwise.

Since:

BlackBerry 10.0.0

bool isAutoUpdateEnabled ()

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

Return:

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

Since:

BlackBerry 10.2.0

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

Retrieves the dialog box's modality.

Return:

The dialog box's modality.

Since:

BlackBerry 10.0.0

int progress ()

Retrieves the progress of the dialog box.

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

The progress of the dialog box.

Since:

BlackBerry 10.0.0

bool rememberMeChecked ()

Retrieves whether the check box for includeRememberMe is selected by default.

To obtain the user selection, use rememberMeSelection() instead.
Return:

true if the check box should be selected by default, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool rememberMeSelection ()

Returns the state of the check box for remembering user selection when the user dismisses the dialog box.

Return:

true if the check box for remembering the user selection was checked, false otherwise.

Since:

BlackBerry 10.0.0

QString rememberMeText ()

Retrieves the text associated with the check box for includeRememberMe.

Return:

The text for the check box for includeRememberMe.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetActivityIndicatorVisible ()

Resets the dialog box's activityIndicatorVisible property to its default value.

Since:

BlackBerry 10.2.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 dialog box to QString::null.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetButtonAreaLimit ()

Resets the maximum number of buttons to accommodate in the dialog box button area without overflow to -1.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetCancelButton ()

Resets the cancel button for this dialog box.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetConfirmButton ()

Resets the confirm button for this dialog box.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetCustomButton ()

Resets the custom action button for this dialog box.

When the button resets, its label is a default-constructed QString so this button is omitted when making show() and exec() requests.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetDefaultButton ()

Resets the default button for this dialog box based on the property's precedence rules.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetDismissAutomatically ()

Resets whether the dialog box is dismissed when a button is selected to true.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetEmoticonsEnabled ()

Resets whether the text can display emoticons to false.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetIcon ()

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

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetIncludeRememberMe ()

Resets the flag to show the check box for remembering user selection to false.

To reset the selection state for the check box, use resetRememberMeChecked().

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetModality ()

Resets the modality of the dialog box to bb::system::SystemUiModality::Application.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetProgress ()

Resets the progress of the dialog box to -1.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetRememberMeChecked ()

Resets the selection state for the check box for includeRememberMe to true.

To reset whether to include the check box use resetIncludeRememberMe().

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetRememberMeText ()

Resets the text for the check box for includeRememberMe to "Remember Me".

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetReturnKeyAction ()

Resets the return key action of the dialog box to bb::system::SystemUiReturnKeyAction::Default.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetState ()

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

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetStatusDetails ()

Resets the progress status details of the dialog box to QString::null.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetStatusMessage ()

Resets the progress status message of the dialog box to QString::null.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetTitle ()

Resets the title of the dialog box 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

bb::system::SystemUiReturnKeyAction::Type returnKeyAction ()

Retrieves the dialog box's return key action.

Return:

The dialog box's return key action.

Since:

BlackBerry 10.0.0

void setActivityIndicatorVisible (
  • boolvisible)

Sets whether an activity indicator is displayed on the title bar of the dialog box.

Parameters
visible

true if the dialog box displays an activity indicator, false otherwise.

Since:

BlackBerry 10.2.0

void setAutoUpdateEnabled (
  • boolupdate)

Sets the autoUpdateEnabled flag of the dialog box.

Parameters
update

true if the dialog box will update automatically, false if the dialog box will not update automatically (in which case the show() method must be called after updating the dialog box presentation properties).

Since:

BlackBerry 10.2.0

void setBody (

Sets the main text of the dialog box.

Parameters
body

The text of the dialog box.

Since:

BlackBerry 10.0.0

void setButtonAreaLimit (
  • intnewButtonAreaLimit)

Sets the maximum number of buttons to accommodate in the dialog box button area without overflow.

Values outside the range [1,3] will reset the property to its default value, -1. If newButtonAreaLimit is smaller than the number of buttons that will be displayed, all buttons are stacked vertically.
Parameters
newButtonAreaLimit

The maximum number of buttons in the button area.

Since:

BlackBerry 10.0.0

void setDefaultButton (

Sets the dialog box's default button.

newDefaultButton must be one of the buttons managed by this instance, or NULL. If NULL is specified, then no button is associated with the return key action.

If a non-managed button is specified, then this property is undefined.
Parameters
newDefaultButton

The button to associate with the return key action.

Since:

BlackBerry 10.0.0

void setDismissAutomatically (
  • boolautomaticDismissal)

Sets whether the dialog box is dismissed when a button is selected.

Parameters
automaticDismissal

The preference of whether to dismiss the dialog box automatically.

Since:

BlackBerry 10.0.0

void setEmoticonsEnabled (
  • boolnewEmoticonsEnabled)

Sets whether the text can be displayed as emoticons.

Parameters
newEmoticonsEnabled

Whether the dialog box supports emoticons.

Since:

BlackBerry 10.0.0

void setIcon (

Sets the icon for the dialog box.

Parameters
icon

The local path to the icon for the dialog box.

Since:

BlackBerry 10.0.0

void setIncludeRememberMe (
  • boolvalue)

Sets the flag indicating if a check box for remembering user selection should be included in the dialog box.

Parameters
value

true if a check box for remembering user selection should be included, false otherwise.

Since:

BlackBerry 10.0.0

void setModality (

Sets the modality for the dialog box.

Parameters
newModality

The new modality preference.

Since:

BlackBerry 10.0.0

void setProgress (
  • intnewProgress)

Sets the progress of the dialog box.

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 dialog box.

Since:

BlackBerry 10.0.0

void setRememberMeChecked (
  • boolnewRememberMeSelected)

Sets whether the check box for includeRememberMe is selected by default.

Parameters
newRememberMeSelected

true if the check box should be selected by default, false otherwise.

Since:

BlackBerry 10.0.0

void setRememberMeText (

Sets the text associated with the check box for includeRememberMe.

Parameters
newRememberMeText

The new text for the check box for includeRememberMe.

Since:

BlackBerry 10.0.0

void setReturnKeyAction (

Sets the return key action for the dialog box.

Parameters
newReturnKeyAction

The new return key action.

Since:

BlackBerry 10.0.0

void setState (

Sets the state of progress of the dialog box.

Parameters
newProgressState

The progress state of the dialog box.

Since:

BlackBerry 10.0.0

void setStatusDetails (

Sets the status details for the progress of the task represented by the dialog box.

Parameters
newStatusDetails

The status details of the progress of the dialog box.

Since:

BlackBerry 10.0.0

void setStatusMessage (

Sets the status message for the progress of the task represented by the dialog box.

Parameters
newStatusMessage

The status message of the progress of the dialog box.

Since:

BlackBerry 10.0.0

void setTitle (

Sets the title for the dialog box.

Parameters
title

The title of the dialog box.

Since:

BlackBerry 10.0.0

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

Retrieves the state of the progress of the task represented by the dialog box.

Return:

The progress state.

Since:

BlackBerry 10.0.0

QString statusDetails ()

Retrieves the status details of the progress of the dialog box.

Return:

The status details of the dialog box.

Since:

BlackBerry 10.0.0

QString statusMessage ()

Retrieves the status message of the progress of the dialog box.

Return:

The status message of the dialog box.

Since:

BlackBerry 10.0.0

QString title ()

Retrieves the title for the dialog box.

Return:

The title of the dialog box.

Since:

BlackBerry 10.0.0

Public Slots

void cancel ()

Cancels the dialog box if it is still displayed.

Since:

BlackBerry 10.0.0

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

Displays the dialog box based on current property values.

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

Unlike show(), this function will block until a button selection is made. If the dialog box is already on the screen, this method will return 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 dialog box 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 dialog box based on current property values.

The result of the request can be retrieved with result, or by using the finished () signal. The button selection 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 dialog box based on the current property values.

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

Since:

BlackBerry 10.2.0

Signals

void activityIndicatorVisibleChanged (
  • boolvalue)

Emitted when the activityIndicatorVisible property is changed programmatically.

Parameters
value

The new value of the activityIndicatorVisible property.

Since:

BlackBerry 10.2.0

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 buttonAreaLimitChanged (
  • intnewButtonAreaLimit)

Emitted when the buttonAreaLimit property is changed programmatically.

Parameters
newButtonAreaLimit

The new value of the buttonAreaLimit property.

Since:

BlackBerry 10.0.0

void defaultButtonChanged (

Emitted when the defaultButton property is changed programmatically.

Parameters
newDefaultButton

The new value of the defaultButton property, or NULL if none is set.

Since:

BlackBerry 10.0.0

void dismissAutomaticallyChanged (
  • boolautomaticDismissal)

Emitted when the dismissAutomatically property is changed programmatically.

Parameters
automaticDismissal

The new value of the dismissAutomatically property.

Since:

BlackBerry 10.0.0

void emoticonsEnabledChanged (
  • boolnewEmoticonsEnabled)

Emitted when the emoticonsEnabled property is changed programmatically.

Parameters
newEmoticonsEnabled

The new value of the emoticonsEnabled property.

Since:

BlackBerry 10.0.0

void finished (

Emitted when a request is completed.

The button selection can be retrieved with buttonSelection(). The state of the check box for remembering the content of this dialog box can be retrieved using rememberMeSelection().
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 includeRememberMeChanged (
  • boolvalue)

Emitted when the includeRememberMe property is changed programmatically.

Parameters
value

The new value of the includeRememberMe 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 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 rememberMeCheckedChanged (
  • boolnewRememberMeSelected)

Emitted when the rememberMeChecked property is changed programmatically.

When the user dismisses the dialog box, the user selection is available via rememberMeSelection().
Parameters
newRememberMeSelected

The new value of the rememberMeChecked property.

Since:

BlackBerry 10.0.0

void rememberMeTextChanged (

Emitted when the rememberMeText property is changed programmatically.

Parameters
newRememberMeText

The new value of the rememberMeText property.

Since:

BlackBerry 10.0.0

void returnKeyActionChanged (

Emitted when the returnKeyAction property is changed programmatically.

Parameters
newReturnKeyAction

The new value of the returnKeyAction 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 statusDetailsChanged (

Emitted when the statusDetails property is changed programmatically.

Parameters
newStatusDetails

The new value of the statusDetails 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 titleChanged (

Emitted when the title property is changed programmatically.

Parameters
value

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