NotificationDialog

#include <bb/platform/NotificationDialog>

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

A notification that will be shown to the user using a dialog box.

The notification also triggers effects such as vibration, LED flashing, sound playing, and so on. The effects are dependent on the notification settings of the application. Settings like Universal Inbox integration and badges will not be applied.

Since:

BlackBerry 10.0.0

Public Functions Index

NotificationDialog (QObject *parent=0)
virtual ~NotificationDialog ()
QStringtitle () const
QStringbody () const
boolrepeat () const
QUrlsoundUrl () const
voidsetTitle (const QString &title)
voidsetBody (const QString &body)
voidsetRepeat (bool repeat)
voidsetSoundUrl (const QUrl &newSoundUrl)
voidappendButton (bb::system::SystemUiButton *button)
intbuttonCount () const
bb::system::SystemUiButton *buttonAt (int index) const
voidclearButtons ()
voidresetTitle ()
voidresetBody ()
voidresetRepeat ()
voidresetSoundUrl ()
bb::platform::NotificationResult::Typeresult () const
bb::platform::NotificationError::Typeerror () const
Q_INVOKABLE bb::system::SystemUiButton *buttonSelection () const

Public Slots Index

voidshow ()
bb::platform::NotificationResult::Typeexec ()
voidcancel ()

Signals Index

voidfinished (bb::platform::NotificationResult::Type value)
voidtitleChanged (const QString &value)
voidbodyChanged (const QString &value)
voidrepeatChanged (bool value)
voidsoundUrlChanged (const QUrl &newSoundUrl)

Properties

QString title

Represents the title of the notification.

The notification settings determine whether and where the title is shown.

Since:

BlackBerry 10.0.0

QString body

Represents the main text of the notification.

The notification settings determine whether and where the body is shown.

Since:

BlackBerry 10.0.0

bool repeat

Represents whether the triggered effects of the notification should repeat.

Repeating effects include playing a sound.

Since:

BlackBerry 10.0.0

QUrl soundUrl

Represents the location of the sound to be used when the notification is posted.

When the notification setting allows for sounds to be played, this property overrides the user preference for which sound to play. You must specify the soundUrl as a file URI to a public asset or a shared asset on the device. You can set a local asset to be a public asset in the Assets tab of the bar-descriptor.xml file of your project.

Permissions:

You must set the access_shared permission for your app to access shared files.

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< bb::system::SystemUiButton > buttons[read-only]

Represents any buttons to include in the dialog box.

When the user selects one of these buttons, the finished() signal will be emitted with a parameter value of bb::platform::NotificationResult::ButtonSelection. If no buttons are supplied, show() requests will fail.

Since:

BlackBerry 10.0.0

bb::platform::NotificationResult::Type result[read-only]

Represents the result of the last completed request.

Since:

BlackBerry 10.0.0

bb::platform::NotificationError::Type error[read-only]

Represents the last error encountered.

This property is only valid when result() is bb::platform::NotificationResult::Error.

Since:

BlackBerry 10.0.0

Public Functions

NotificationDialog (

The default property is buttons.

Constructs a new instance of a notification dialog box.
Parameters
parent

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

BlackBerry 10.0.0

virtual~NotificationDialog ()

Destructor.

Since:

BlackBerry 10.0.0

QString title ()

Retrieves the title associated with this notification.

Return:

The title of the notification.

Since:

BlackBerry 10.0.0

QString body ()

Retrieves the text associated with this notification.

Return:

The text of the notification.

Since:

BlackBerry 10.0.0

bool repeat ()

Retrieves the setting of whether or not to repeat notification settings such as vibration, LED, and so on.

Return:

true if the notification settings should be repeated.

Since:

BlackBerry 10.0.0

QUrl soundUrl ()

Retrieves the sound associated with this notification.

If empty, the user setting will be used.
Return:

The sound URL of the notification.

Since:

BlackBerry 10.0.0

void setTitle (

Sets the title of the notification.

Parameters
title

The title for the notification.
Since:

BlackBerry 10.0.0

void setBody (

Sets the text of the notification.

Parameters
body

The body for the notification.
Since:

BlackBerry 10.0.0

void setRepeat (
  • boolrepeat)

Sets whether or not the notification settings like vibration, LED, etc should be repeated.

Parameters
repeat

The preference for repeating notification settings.
Since:

BlackBerry 10.0.0

void setSoundUrl (
  • const QUrl &newSoundUrl)

Sets the sound of the notification.

You must specify the soundUrl as a file URI to a public asset or a shared asset on the device. You can set a local asset to be a public asset in the Assets tab of the bar-descriptor.xml file of your project.

Permissions:

You must set the access_shared permission for your app to access shared files.

Parameters
newSoundUrl

The soundUrl for the notification.
Since:

BlackBerry 10.0.0

void appendButton (

Appends button to the list of buttons for this notification dialog box.

The notification will become the parent of the button and be responsible for destroying it. A button can only be added once.
Parameters
button

The button to append.
Since:

BlackBerry 10.0.0

int buttonCount ()

Retrieves the number of buttons added to the notification.

Return:

The number of buttons.

Since:

BlackBerry 10.0.0

bb::system::SystemUiButton * buttonAt (
  • intindex)

Retrieves the button at index.

This instance retains ownership of the returned value.
Parameters
index

An index into the list of buttons.

Return:

The button at index or null if an invalid index is provided.

Since:

BlackBerry 10.0.0

void clearButtons ()

Clears the list of buttons for this notification.

The button instances will be deleted.

Since:

BlackBerry 10.0.0

void resetTitle ()

Resets the title for the notification.

This resets the title property to its context-specific default value. The default is QString::null.

Since:

BlackBerry 10.0.0

void resetBody ()

Resets the body for the notification.

This resets the body property to its context-specific default value. The default is QString::null.

Since:

BlackBerry 10.0.0

void resetRepeat ()

Resets whether effects triggered by the notification should be repeated to not repeat.

Since:

BlackBerry 10.0.0

void resetSoundUrl ()

Resets the sound for the notification.

When reset, the user setting will be used.

Since:

BlackBerry 10.0.0

bb::platform::NotificationResult::Type result ()

Retrieves the result of the last completed request.

If no request has been made, or if a request is pending, bb::platform::NotificationResult::None is returned.
Return:

The result of the last completed request.

Since:

BlackBerry 10.0.0

bb::platform::NotificationError::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 selected when a button selection is made.

If no button has been selected, a null pointer will be returned.

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.

Since:

BlackBerry 10.0.0

Public Slots

void show ()

Displays or updates the dialog box based on current property values.

The dialog result can be retrieved with buttonSelection().

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

Since:

BlackBerry 10.0.0

bb::platform::NotificationResult::Type exec ()

Displays the dialog box based on current property values.

The button selection can be retrieved with buttonSelection().

Unlike show(), this function will block until a button selection is made.
Return:

The result of the request.

Since:

BlackBerry 10.0.0

void cancel ()

Cancels the dialog box if it is still displayed.

Since:

BlackBerry 10.0.0

Signals

void finished (

Emitted when a request is completed.

Parameters
value

The result of the request.
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

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 repeatChanged (
  • boolvalue)

Emitted when the repeat property is changed programmatically.

Parameters
value

The new value for the repeat property.
Since:

BlackBerry 10.0.0

void soundUrlChanged (
  • const QUrl &newSoundUrl)

Emitted when the soundUrl property changes.

Parameters
newSoundUrl

The new value for the soundUrl property.
Since:

BlackBerry 10.0.0