NotificationDialog

Since: BlackBerry 10.0.0

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


Overview

Public Functions Index

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

Public Slots Index

Signals Index

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

Properties

QString body

Represents the main text of the notification.

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

bool repeat

Represents whether the triggered effects of the notification should repeat.

Repeating effects include playing a sound.

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

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

QString title

Represents the title of the notification.

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

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

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

void appendButton (

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

This button will trigger invokeRequest when it is pressed by the user. The client will still receive a button selection as it does for buttons that do not have associated invoke requests.

The notification dialog will become the parent of the button and be responsible for destroying it. A button can only be added once. The invoke request must explicitly specify a target. All other invoke attributes are optional.
Parameters
button

The button to append.

invoke

The invoke request associated with the button

Since:

BlackBerry 10.3.0

QString body ()

Retrieves the text associated with this notification.

Return:

The text of the notification.

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

int buttonCount ()

Retrieves the number of buttons added to the notification.

Return:

The number of buttons.

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

void clearButtons ()

Clears the list of buttons for this notification along with any associated invoke requests.

The button instances will be deleted.

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

bb::system::InvokeRequest invokeRequestAt (
  • intindex)

Retrieves the invoke request associated with the button at index.

The returned value is a copy of the invoke request associated with the button.
Parameters
index

An index into the list of buttons.

Return:

The invoke request associated with button at index or an empty invoke request if no invoke was associated with the specified button index or if an invalid index is provided.

Since:

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

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

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

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

void setBody (

Sets the text of the notification.

Parameters
body

The body for the notification.

Since:

BlackBerry 10.0.0

bool setInvokeRequestAt (

Sets or replaces the InvokeRequest associated with the button at index.

index should be the index of an existing button before calling this method. If an InvokeRequest without a target is set, no invoke will occur when the button is pressed.
Parameters
index

An index into the list of buttons.

invokeRequest

Value to set for invoke request associated with the button

Return:

false if the supplied index was invalid; true otherwise.

Since:

BlackBerry 10.3.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 setTitle (

Sets the title of the notification.

Parameters
title

The title for the notification.

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

QString title ()

Retrieves the title associated with this notification.

Return:

The title of the notification.

Since:

BlackBerry 10.0.0

Public Slots

void cancel ()

Cancels the dialog box if it is still displayed.

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

Signals

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.

Parameters
value

The result of the request.

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

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



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

comments powered by Disqus