Nemo QML Plugins Notifications

API Documentation

Notification Class

Allows notifications to be published More...

Header:	#include <notification.h>
Instantiated By:	Notification

Public Types

enum	CloseReason { Expired, DismissedByUser, Closed }
enum	Progress { ProgressIndeterminate }
enum	Urgency { Low, Normal, Critical }

Properties

appIcon : QString
appName : QString
body : QString
category : QString
expireTimeout : qint32
icon : QString
iconData : QImage
isTransient : bool
itemCount : int
maxContentLines : int
previewBody : QString

previewSummary : QString
progress : QVariant
remoteActions : QVariantList
replacesId : quint32
sound : QString
soundName : QString
subText : QString
summary : QString
timestamp : QDateTime
urgency : Urgency

Public Functions

	Notification(QObject *parent = 0)
QString	appIcon() const
QString	appName() const
QString	body() const
QString	category() const
void	close()
qint32	expireTimeout() const
QVariant	hintValue(const QString &hint) const
QString	icon() const
QImage	iconData() const
bool	isTransient() const
int	itemCount() const
int	maxContentLines() const
QString	previewBody() const
QString	previewSummary() const
QVariant	progress() const
void	publish()
QVariantList	remoteActions() const
quint32	replacesId() const
void	resetProgress()
void	setAppIcon(const QString &appIcon)
void	setAppName(const QString &appName)
void	setBody(const QString &body)
void	setCategory(const QString &category)
void	setExpireTimeout(qint32 milliseconds)
void	setHintValue(const QString &hint, const QVariant &value)
void	setIcon(const QString &icon)
void	setIconData(const QImage &image)
void	setIsTransient(bool value)
void	setItemCount(int itemCount)
void	setMaxContentLines(int max)
void	setPreviewBody(const QString &previewBody)
void	setPreviewSummary(const QString &previewSummary)
void	setProgress(const QVariant &value)
void	setRemoteActions(const QVariantList &remoteActions)
void	setReplacesId(quint32 id)
void	setSound(const QString &sound)
void	setSoundName(const QString &soundName)
void	setSubText(const QString &subText)
void	setSummary(const QString &summary)
void	setTimestamp(const QDateTime &timestamp)
void	setUrgency(Urgency urgency)
QString	sound() const
QString	soundName() const
QString	subText() const
QString	summary() const
QDateTime	timestamp() const
Urgency	urgency() const

Signals

void	actionInvoked(const QString &name)
void	appIconChanged()
void	appNameChanged()
void	bodyChanged()
void	categoryChanged()
void	clicked()
void	closed(uint reason)
void	expireTimeoutChanged()
void	iconChanged()
void	iconDataChanged()
void	isTransientChanged()
void	itemCountChanged()
void	maxContentLinesChanged()
void	previewBodyChanged()
void	previewSummaryChanged()
void	progressChanged()
void	remoteActionsChanged()
void	replacesIdChanged()
void	soundChanged()
void	soundNameChanged()
void	subTextChanged()
void	summaryChanged()
void	timestampChanged()
void	urgencyChanged()

Static Public Members

QList<QObject *>	notifications()
QList<QObject *>	notifications(const QString &owner)
QList<QObject *>	notificationsByCategory(const QString &category)
QVariant	remoteAction(const QString &name, const QString &displayName, const QString &service = QString(), const QString &path = QString(), const QString &iface = QString(), const QString &method = QString(), const QVariantList &arguments = QVariantList())

Detailed Description

Allows notifications to be published

The Notification class is a convenience class for using notifications based on the Desktop Notifications Specification as implemented in Nemo.

This class allows clients to create instances of notifications, which can be used to communicate to the home screen's Notification Manager via D-Bus. This simplifies the process of creating, listing and closing notifications, since the necessary communications are handled by the class.

Member Type Documentation

enum Notification::CloseReason

This enum type describes the reason given when a notification is reported as closed.

Constant	Value	Description
`Notification::Expired`	`0`	The notification expireTimeout period elapsed.
`Notification::DismissedByUser`	`1`	The notification was dismissed by user action.
`Notification::Closed`	`2`	The notification was closed programatically.

enum Notification::Progress

enum Notification::Urgency

This enum type describes the urgency level of a notification.

Constant	Value	Description
`Notification::Low`	`0`	The notification is not urgent.
`Notification::Normal`	`1`	The notification is like most other notifications.
`Notification::Critical`	`2`	The notification is of urgent relevance to the user.

Property Documentation

appIcon : QString

The icon for the application that this notification is associated with. The value can be a URI, an absolute filesystem path, or a token to be interpreted by the theme image provider.

This property is transmitted as the standard Notify parameter "app_icon".

Access functions:

QString	appIcon() const
void	setAppIcon(const QString &appIcon)

Notifier signal:

void	appIconChanged()

appName : QString

The application name associated with this notification, for display purposes.

The application name should be the formal name, localized if appropriate.

This property is transmitted as the standard Notify parameter "app_name".

Access functions:

QString	appName() const
void	setAppName(const QString &appName)

Notifier signal:

void	appNameChanged()

body : QString

Optional detailed body text.

This property is transmitted as the standard Notify parameter "body".

Access functions:

QString	body() const
void	setBody(const QString &body)

Notifier signal:

void	bodyChanged()

category : QString

The category whose properties should be applied to the notification by the Notification Manager.

Properties defined by the category definition file will be applied to the notification, unless those properties are already set in the notification.

This property is transmitted as the standard hint value "category".

Access functions:

QString	category() const
void	setCategory(const QString &category)

Notifier signal:

void	categoryChanged()

expireTimeout : qint32

The number of milliseconds after display at which the notification should be automatically closed. A value of zero indicates that the notification should not close automatically, while -1 indicates that the notification manager should decide the expiration timeout.

Defaults to -1.

This property is transmitted as the standard Notify parameter "expire_timeout".

Access functions:

qint32	expireTimeout() const
void	setExpireTimeout(qint32 milliseconds)

Notifier signal:

void	expireTimeoutChanged()

icon : QString

Icon of the notication. The value can be a URI, an absolute filesystem path, or a token to be interpreted by the theme image provider.

Alternatively the iconData property may be used to set a decoded image.

This property is transmitted as the standard hint value "image-path".

Access functions:

QString	icon() const
void	setIcon(const QString &icon)

Notifier signal:

void	iconChanged()

See also iconData.

iconData : QImage

An image to be shown on the notification.

Alternatively the icon property may be used to a set the URI of a persistent image file or a theme identifier for the icon.

This property is transmitted as the standard hint value "image-data".

Access functions:

QImage	iconData() const
void	setIconData(const QImage &image)

Notifier signal:

void	iconDataChanged()

See also icon.

isTransient : bool

A property suggesting that notification should be only briefly shown.

This property is transmitted as the standard hint value "transient".

Access functions:

bool	isTransient() const
void	setIsTransient(bool value)

Notifier signal:

void	isTransientChanged()

itemCount : int

The number of items represented by the notification. For example, a single notification can represent four missed calls by setting the count to 4. Defaults to 1.

This property is transmitted as the extension hint value "x-nemo-item-count".

Access functions:

int	itemCount() const
void	setItemCount(int itemCount)

Notifier signal:

void	itemCountChanged()

maxContentLines : int

A property suggesting the maximum amount of content to display for the notification. The content lines include the summary line, so a single-line notification does not display any body text.

This property is transmitted as the extension hint value "x-nemo-max-content-lines".

Access functions:

int	maxContentLines() const
void	setMaxContentLines(int max)

Notifier signal:

void	maxContentLinesChanged()

previewBody : QString

Body text to be shown in the preview banner for the notification, if any.

If this is not set it will automatically be set to the body value when the notification is published.

When the previewSummary or previewBody is specified, a preview of the notification will be generated by home screen at publication (unless the Notification Manager chooses to suppress the preview).

This property is transmitted as the extension hint value "x-nemo-preview-body".

Access functions:

QString	previewBody() const
void	setPreviewBody(const QString &previewBody)

Notifier signal:

void	previewBodyChanged()

previewSummary : QString

Summary text to be shown in the preview banner for the notification, if any.

If this is not set it will automatically be set to the summary value when the notification is published.

When the previewSummary or previewBody is specified, a preview of the notification will be generated by home screen at publication (unless the Notification Manager chooses to suppress the preview).

This property is transmitted as the extension hint value "x-nemo-preview-summary".

Access functions:

QString	previewSummary() const
void	setPreviewSummary(const QString &previewSummary)

Notifier signal:

void	previewSummaryChanged()

progress : QVariant

Property containing the progress the notification represent. Value can be undefined for no progress, Notification::ProgressIndeterminate for indeterminate state or real between 0.0 and 1.0 to represent progress percentage.

Access functions:

QVariant	progress() const
void	setProgress(const QVariant &value)
void	resetProgress()

Notifier signal:

void	progressChanged()

remoteActions : QVariantList

The remote actions registered for potential invocation by this notification.

Remote actions may specify D-Bus calls to be emitted by the Notification Manager when a notification is activated by the user. remoteAction describes the format of a remote action specification.

Note: the action named "default" will be invoked when the user activates the main notification item. If the user activates a notification group, the action named "app" will be invoked, if that action is shared by all members of the group.

This property is transmitted as the Notify parameter "actions" and the extension hint value "x-nemo-remote-action-<name>".

Access functions:

QVariantList	remoteActions() const
void	setRemoteActions(const QVariantList &remoteActions)

Notifier signal:

void	remoteActionsChanged()

See also remoteAction().

replacesId : quint32

The ID that should be used to replace or remove this notification.

If a notification is published with a non-zero ID, it will replace any existing notification with that ID, without alerting the user to any changes. An unpublished notification has a ID of zero. The ID is automatically updated to contain the published ID after publication is reported by the Notification Manager.

This property is transmitted as the standard Notify parameter "replaces_id".

Access functions:

quint32	replacesId() const
void	setReplacesId(quint32 id)

Notifier signal:

void	replacesIdChanged()

sound : QString

The file path of a sound to be played when the notification is shown.

This property is transmitted as the hint value "sound-file".

Access functions:

QString	sound() const
void	setSound(const QString &sound)

Notifier signal:

void	soundChanged()

soundName : QString

The name of a sound to be played when the notification is shown.

This property is transmitted as the hint value "sound-name", names following the freedesktop.org sound naming specification. Sound name can be e.g. "message-new-instant" or "message-new-email".

Access functions:

QString	soundName() const
void	setSoundName(const QString &soundName)

Notifier signal:

void	soundNameChanged()

subText : QString

Sub-text of the notification, if any.

This can indicate some brief secondary information, such as the sender's email address in the case of a "new email" notification.

This property is transmitted as the extension hint value "x-nemo-sub-text".

Access functions:

QString	subText() const
void	setSubText(const QString &subText)

Notifier signal:

void	subTextChanged()

summary : QString

The summary text briefly describing the notification. The summary should give a brief, single-line description of the notification.

This property is transmitted as the standard Notify parameter "summary".

Access functions:

QString	summary() const
void	setSummary(const QString &summary)

Notifier signal:

void	summaryChanged()

timestamp : QDateTime

The timestamp is typically associated with an event that the notification relates to, rather than for the creation of the notification itself. If not specified, the notification's timestamp will become the time of publification.

This property is transmitted as the extension hint value "x-nemo-timestamp".

Access functions:

QDateTime	timestamp() const
void	setTimestamp(const QDateTime &timestamp)

Notifier signal:

void	timestampChanged()

urgency : Urgency

The urgency level of the notification.

Urgency level is interpreted by the Notification Manager at publication. It may decide to display or to suppress display of the notification depending on the current user activity or device state, where notifications with Critical urgency are more likely to be displayed.

Defaults to Normal urgency.

This property is transmitted as the standard hint value "urgency".

Access functions:

Urgency	urgency() const
void	setUrgency(Urgency urgency)

Notifier signal:

void	urgencyChanged()

Member Function Documentation

Notification::Notification(QObject **parent* = 0)

Constructs a new Notification, optionally using parent as the object parent.

`[signal]` void Notification::actionInvoked(const QString &name)

Emitted when a notification action is activated by the user. name indicates the name of the invoked action.

Handling the actionInvoked signal is only effective if the process is running when the user activates the notification, which may occur long after the notification is published.

`[signal]` void Notification::clicked()

Emitted when the notification is activated by the user.

Handling the clicked signal is only effective if the process is running when the user activates the notification, which may occur long after the notification is published. A more robust solution is to register a 'remote action' with the Notification Manager, so that a handler can be started running and invoked to service the request.

See also remoteActions().

void Notification::close()

Closes the notification identified by replacesId.

`[signal]` void Notification::closed(uint reason)

Emitted when the notification is reported closed by the notification manager. The reason value corresponds to a value defined by Notification::CloseReason.

QVariant Notification::hintValue(const QString &hint) const

Returns the value of the hint named hint.

See also setHintValue().

`[static]` QList<QObject *> Notification::notifications()

Returns a list of existing notifications whose 'x-nemo-owner' hint value matches the process name of the running process.

All notifications produced by calling publish() are set to contain a hint 'x-nemo-owner' with the value of process name of the running process (unless that hint is already specified). This allows previously generated notifications to be easily retrieved via this function.

The returned objects are instances of the Notification class. The caller takes ownership and should destroy them when they are no longer required.

`[static]` QList<QObject > Notification::notifications(const QString &owner*)

Returns a list of existing notifications whose 'x-nemo-owner' hint value matches owner.

The returned objects are instances of the Notification class. The caller takes ownership and should destroy them when they are no longer required.

`[static]` QList<QObject > Notification::notificationsByCategory(const QString &category*)

Returns a list of existing notifications whose 'category' hint value matches category. This requires privileged access rights from the caller.

The returned objects are instances of the Notification class. The caller takes ownership and should destroy them when they are no longer required.

void Notification::publish()

Publishes the current state of the notification to the Notification Manager.

If replacesId is zero, a new notification will be created and replacesId will be updated to contain that ID. Otherwise the existing notification with the given ID is updated with the new details.

`[static]` QVariant Notification::remoteAction(const QString &name, const QString &displayName, const QString &service = QString(), const QString &path = QString(), const QString &iface = QString(), const QString &method = QString(), const QVariantList &arguments = QVariantList())

Helper function to assemble an object specifying a remote action, potentially to be invoked via D-Bus.

If service, path, iface, method, and optionally arguments are set, the action can trigger a D-Bus callback when activated by the user.

name: the name of the action. "default" for the whole notification icon. If empty, will generate a name
displayName: the name of the action to be displayed to user. May not get displayed for "default", in which case it can be empty.
service: the name of the D-Bus service to be invoked
path: the object path to be invoked via D-Bus
iface: the interface to be invoked via D-Bus
method: the method of the interface to be invoked via D-Bus
arguments: the optional arguments to be passed to the method invoked via D-Bus

void Notification::setHintValue(const QString &hint, const QVariant &value)

Sets the value of the hint named hint to value.

See also hintValue().

Nemo QML Plugins Notifications

Contents

Notification Class

Public Types

Properties

Public Functions

Signals

Static Public Members

Detailed Description

Member Type Documentation

enum Notification::CloseReason

enum Notification::Progress

enum Notification::Urgency

Property Documentation

appIcon : QString

appName : QString

body : QString

category : QString

expireTimeout : qint32

icon : QString

iconData : QImage

isTransient : bool

itemCount : int

maxContentLines : int

previewBody : QString

previewSummary : QString

progress : QVariant

remoteActions : QVariantList

replacesId : quint32

sound : QString

soundName : QString

subText : QString

summary : QString

timestamp : QDateTime

urgency : Urgency

Member Function Documentation

Notification::Notification(QObject *parent = 0)

[signal] void Notification::actionInvoked(const QString &name)

[signal] void Notification::clicked()

void Notification::close()

[signal] void Notification::closed(uint reason)

QVariant Notification::hintValue(const QString &hint) const

[static] QList<QObject *> Notification::notifications()

[static] QList<QObject *> Notification::notifications(const QString &owner)

[static] QList<QObject *> Notification::notificationsByCategory(const QString &category)

void Notification::publish()

[static] QVariant Notification::remoteAction(const QString &name, const QString &displayName, const QString &service = QString(), const QString &path = QString(), const QString &iface = QString(), const QString &method = QString(), const QVariantList &arguments = QVariantList())

void Notification::setHintValue(const QString &hint, const QVariant &value)

Notification::Notification(QObject **parent* = 0)

`[signal]` void Notification::actionInvoked(const QString &name)

`[signal]` void Notification::clicked()

`[signal]` void Notification::closed(uint reason)

`[static]` QList<QObject *> Notification::notifications()

`[static]` QList<QObject > Notification::notifications(const QString &owner*)

`[static]` QList<QObject > Notification::notificationsByCategory(const QString &category*)

`[static]` QVariant Notification::remoteAction(const QString &name, const QString &displayName, const QString &service = QString(), const QString &path = QString(), const QString &iface = QString(), const QString &method = QString(), const QVariantList &arguments = QVariantList())