Notification QML Type

An abstraction layer to enable QML applications to issue notifications to the System UI. More...

Import Statement: import QtApplicationManager

Properties

Signals

Methods

Detailed Description

The Notification type is available for QML applications by either creating a Notification item statically or by dynamically calling ApplicationInterface::createNotification. A System UI can also create Notification instances. For all other applications and services, the notification service of the application manager is available via a freedesktop.org compliant org.freedesktop.Notifications D-Bus interface.

Note: Most of the property documentation text is copied straight from the org.freedesktop.Notifications specification because it is not possible to directly link to the documentation of a specific property.

The server/System UI side of the notification infrastructure is implemented by NotificationManager.

Property Documentation

acknowledgeable : bool

Holds whether the notification can be acknowledged by the user - typically, by clicking on it. This action is reported via the acknowledged() signal.

The default value is false.


actions : list<object>

Holds a list of the possible actions the user can choose from. Every key in this map is an actionId and its corresponding value is an actionText. The notification-manager should eiher display the actionText or an icon, depending on the showActionsAsIcons property.

See also actionTriggered().


body : string

Holds a multi-line body of text. Each line is a paragraph, and server implementations are free to word wrap dthem as they see fit.

The body may contain simple HTML markup. If the body is omitted, just the summary is displayed.


category : string

Holds the type of this notification (optional).

Notifications can optionally have a category indicator. Although neither the client or the server must support this, some may choose to. Servers that implement categories may use them to intelligently display the notification in a specific way, or group notifications of similar types together.


dismissOnAction : bool

Holds whether the notification manager should dismiss the notification after user action (for example, clicking one of the supplied action texts or images).

The default value is false.


extended : object

Holds a custom variant property that lets the user attach arbitrary meta-data to this notification.

Note: This is an application manager specific extension to the protocol: it uses the x-pelagicore-extended hint to communicate this value.


icon : url

Holds a URL to an icon associated with this notification (optional).

The icon should identify the application which created this notification.

See also image.


image : url

Holds a URL to an image associated with this notification (optional).

The image should not be used to identify the application (see icon for this), but rather when the notification itself can be assigned an image (for example, showing an album cover in a "Now Playing" notification).

See also icon.


notificationId : int [read-only]

Holds the system-wide unique id of this notification.

The id is 0 until this notification is made visible (and thus published to the server). This property is read-only as the id is allocated by the server.


priority : int

Holds the priority of this notification. The actual value is implementation specific, but ideally any implementation should use the defined values from the freedesktop.org specification, available via the Priority enum:

NameValue
Low0
Normal1
Critical2

The default value is Normal.


progress : qreal

Holds a floating-point value between [0.0 ... 1.0] which can be used to show a progress-bar on the notification. The special value -1 can be used to request a busy indicator. The default value is -1.

Note: This is an application manager specific extension to the protocol: it uses the x-pelagicore-progress hint to communicate this value.


showActionsAsIcons : bool

Holds a hint supplied by the client on how to present the actions. If this property is false, the notification actions should be shown in text form. Otherwise, the actionId should be taken as an icon name conforming to the freedesktop.org icon naming specification (in a closed system, these could also be any icon specification string that the notification server understands).

The default value is false.

See also icon.


showProgress : bool

A boolean value describing whether a progress-bar/busy-indicator should be shown as part of the notification.

The default value is false.

Note: This is an application manager specific extension to the protocol: it uses the x-pelagicore-show-progress hint to communicate this value.


sticky : bool

If this property is set to false, the notification should be removed after timeout milliseconds. Otherwise, the notification is "sticky" and should stay visible until the user acknowledges it.

The default value is false.


summary : string

Holds a single line overview of the notification.

For instance, "You have mail" or "A friend has come online". Generally, it should not exceed 40 characters, though this is not a requirement (server implementations should word wrap it if necessary).


timeout : int

In case of non-sticky notifications, this value specifies after how many milliseconds the notification should be removed from the screen.

The default value is 2000.

See also sticky.


visible : bool

Instructs the system's notification manager to either show or hide this notification. A notification needs to be set visible only once, even if its properties are changed afterwards - these changes are communicated to the server automatically.

Note: This property is just a hint to the notification manager; how and when a notifications actually appears on the screen is up to the server-side implementation.

The default value is false.

See also show() and hide().


Signal Documentation

acknowledged()

This signal is emitted when this notification was acknowledged on the server side - most likely due to the user clicking on the notification.

Note: The corresponding handler is onAcknowledged.


actionTriggered(string actionId)

This signal is emitted when an action identified by actionId of this notification was triggered on the server side.

Note: The actionId can be an arbitrary string: It may or may not represent one of the registered actions, and needs to be explicitly checked.

Note: The corresponding handler is onActionTriggered.


Method Documentation

hide()

An alias for visible = false.

See also visible.


show()

An alias for visible = true.

See also visible.


update()

Updates notification, which was already shown.

See also show.


© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.