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

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 setSubText(const QString &subText)
void setSummary(const QString &summary)
void setTimestamp(const QDateTime &timestamp)
void setUrgency(Urgency urgency)
QString sound() const
QString subText() const
QString summary() const
QDateTime timestamp() const
Urgency urgency() const

Signals

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.

ConstantValueDescription
Notification::Expired0The notification expireTimeout period elapsed.
Notification::DismissedByUser1The notification was dismissed by user action.
Notification::Closed2The notification was closed programatically.

enum Notification::Progress

enum Notification::Urgency

This enum type describes the urgency level of a notification.

ConstantValueDescription
Notification::Low0The notification is not urgent.
Notification::Normal1The notification is like most other notifications.
Notification::Critical2The 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()

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().

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.