Nemo QML Plugins Notifications
API DocumentationNotification QML Type
Allows notifications to be published More...
Import Statement: | import Nemo.Notifications 1.0 |
Instantiates: | Notification |
Properties
- appIcon : string
- appName : string
- body : string
- category : string
- expireTimeout : int
- icon : string
- iconData : image
- isTransient : int
- itemCount : int
- maxContentLines : int
- previewBody : string
- previewSummary : string
- progress : var
- remoteActions : list<variant>
- replacesId : int
- sound : string
- soundName : string
- subText : string
- summary : string
- timestamp : date
- urgency : enumeration
Signals
- actionInvoked(string name)
- clicked()
- closed(uint reason)
Methods
Detailed Description
The Notification type is a convenience type for using notifications based on the Desktop Notifications Specification as implemented in Nemo.
This type 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 type.
Notification content can be specified by setting the various properties on an instance of the Notification type, or can be handled by providing a category, whose properties are automatically applied to matching notifications by the home screen's Notification Manager. Properties set in the notification instance will not be overwritten by values listed in the category.
A minimal example of using this type from a QML application:
Button { Notification { id: notification summary: "Notification summary" body: "Notification body" } text: "Application notification" + (notification.replacesId ? " ID:" + notification.replacesId : "") onClicked: notification.publish() }
When the button is clicked, a new notification is published to the notification manager, having the properties specified in the Notification object definition. Any properties specified by the definition file for the nominated category will be automatically applied by the notification manager during publication. The manager allocates an ID for the notification, and the instance is updated so that this ID is reflected in the replacesId property.
When the user invokes the 'default' action on the notification, the clicked signal is emitted by the notification instance. If the application is no longer running at the relevant time, then the signal will be missed.
A more exhaustive example of usage from a QML application:
Button { Notification { id: notification category: "x-nemo.example" appName: "Example App" appIcon: "/usr/share/example-app/icon-l-application" summary: "Notification summary" body: "Notification body" previewSummary: "Notification preview summary" previewBody: "Notification preview body" itemCount: 5 timestamp: "2013-02-20 18:21:00" remoteActions: [ { "name": "default", "displayName": "Do something", "icon": "icon-s-do-it", "service": "org.nemomobile.example", "path": "/example", "iface": "org.nemomobile.example", "method": "doSomething", "arguments": [ "argument", 1 ] },{ "name": "ignore", "displayName": "Ignore the problem", "icon": "icon-s-ignore", "input" : { "label": "Please select", "editable": true, "choices": [ "Yes", "No", "Maybe" ] }, "service": "org.nemomobile.example", "path": "/example", "iface": "org.nemomobile.example", "method": "ignore", "arguments": [ "argument", 1 ] } ] onClicked: console.log("Clicked") onClosed: console.log("Closed, reason: " + reason) } text: "Application notification" + (notification.replacesId ? " ID:" + notification.replacesId : "") onClicked: notification.publish() }
In this case, the notification includes a specification for 'remote actions', which are D-Bus commands that the notification manager may permit the user to invoke. When an action is invoked on the notification, the corresponding D-Bus command is formulated and invoked, which allows the application to be launched to handled the notification action, if required.
Property Documentation
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".
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".
Optional detailed body text.
This property is transmitted as the standard Notify parameter "body".
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".
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".
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".
An image to be shown on the notification. N.B. this requires QImage typed value, not compatible with Image or such.
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".
A property suggesting that notification should be only briefly shown.
This property is transmitted as the standard hint value "transient".
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".
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".
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".
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".
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.
The remote actions registered for potential invocation by this notification.
Remote actions are specified as a list of objects having the properties 'name', 'displayName, 'icon', 'service', 'path', 'iface', 'method', and 'arguments'. 'Name' is always a required property, and 'displayName' if the action is other than "default" or "app".
If D-Bus callback is needed, then 'service', 'path, 'iface, 'method', and optionally 'arguments' should be set.
For example:
Notification { remoteActions: [ { "name": "default", "displayName": "Do something", "icon": "icon-s-do-it", "service": "org.nemomobile.example", "path": "/example", "iface": "org.nemomobile.example", "method": "doSomething", "arguments": [ "argument", 1 ] } ] }
Notification { remoteAction: [ { "name": "default" }, { "name": "extraAction", "displayName": "Extra action (no callback)" } ] }
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>".
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".
The file path of a sound to be played when the notification is shown.
This property is transmitted as the hint value "sound-file".
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".
Sub-text of the notification, if any.
This indicates 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".
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".
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".
The urgency level of the notification. The value corresponds to one of:
- Notification.Low
- Notification.Normal
- Notification.Critical
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".
Signal Documentation
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.
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. NB registering a D-Bus autostarted service might not be available for all the applications.
See also Notification::remoteActions.
Emitted when the notification is reported closed by the notification manager. The reason value may be any one of:
- Notification.Expired
- Notification.DismissedByUser
- Notification.Closed
Method Documentation
Closes the notification identified by replacesId.
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.