The DBusNotification class emits D-Bus notifications. More...

#include <dbusnotification.h>

Inheritance diagram for QtUtilities::DBusNotification:

Collaboration diagram for QtUtilities::DBusNotification:

Classes
class	Capabilities

Public Types
using	IDType = uint

Public Slots
bool	show ()
	Shows the notification.

bool	show (const QString &message)
	Updates the message and shows/updates the notification.

bool	update (const QString &line)
	Updates the message and shows/updates the notification.

bool	hide ()
	Hides the notification (if still visible).

Signals
void	shown ()
	Emitted when the notification could be shown successful.

void	error ()
	Emitted when the notification couldn't be shown.

void	closed (NotificationCloseReason reason)
	Emitted when the notification has been closed.

void	actionInvoked (const QString &action)
	Emitted when action has been invoked.

Public Member Functions
	DBusNotification (const QString &title, NotificationIcon icon=NotificationIcon::Information, int timeout=10000, QObject *parent=nullptr)
	Creates a new notification (which is not shown instantly).

	DBusNotification (const QString &title, const QString &icon, int timeout=10000, QObject *parent=nullptr)
	Creates a new notification (which is not shown instantly).

	~DBusNotification () override
	Closes the notification if still shown and delete the object.

const QString &	applicationName () const
	Returns the application name to be used.

void	setApplicationName (const QString &applicationName)
	Sets the application name to be used.

const QString &	title () const

void	setTitle (const QString &title)

const QString &	message () const

void	setMessage (const QString &message)
	Sets the message to be shown.

const QString &	icon () const
	Returns the icon name.

void	setIcon (const QString &icon)
	Sets the icon name.

void	setIcon (NotificationIcon icon)
	Sets the icon to one of the pre-defined notification icons.

const QImage	image () const
	Returns the image.

void	setImage (const QImage &image)
	Sets the image.

const QString	imagePath () const
	Returns the image path.

void	setImagePath (const QString &imagePath)
	Sets the image path.

int	timeout () const

void	setTimeout (int timeout)
	Sets the number of milliseconds the notification will be visible after calling show().

int	urgency () const
	Returns the urgency level (0 = low, 1 = normal, 2 = critical).

void	setUrgency (quint8 urgency)
	Sets the urgency level (0 = low, 1 = normal, 2 = critical).

bool	isResident () const
	Returns whether the notification will remain visible after an action has been clicked.

void	setResident (bool resident)
	Sets whether the notification will remain visible after an action has been clicked.

QString	category () const
	Returns the category.

void	setCategory (const QString &category)
	Sets the category.

const QStringList &	actions () const
	Returns the actions for the notification.

void	setActions (const QStringList &actions)
	Sets the actions for the notification.

const QVariantMap &	hints () const

QVariantMap &	hints ()

QVariant	hint (const QString &name) const
	Returns the hint with the specified name.

QVariant	hint (const QString &name, const QString &fallbackNames...) const
	Returns the hint with the specified name.

bool	isVisible () const
	Returns whether the notification is (still) visible.

bool	isPending () const
	Returns whether the notification is about to be shown after calling show() or update() but has not been shown yet.

void	deleteOnCloseOrError ()
	Makes the notification object delete itself when the notification has been closed or an error occurred.

Static Public Member Functions
static bool	isAvailable ()
	Returns whether the notification D-Bus daemon is running.

static bool	queryCapabilities (const std::function< void(Capabilities &&capabilities)> &callback)

Properties
QString	applicationName

QString	title

QString	message
	Returns the assigned message.

QString	icon

int	timeout
	Returns the number of milliseconds the notification will be visible after calling show().

QStringList	actions
	Returns the assigned actions.

bool	visible

bool	pending

Detailed Description

The DBusNotification class emits D-Bus notifications.

D-Bus notifications are only available if the library has been compiled with support for it by specifying CMake option DBUS_NOTIFICATIONS. If support is available, the macro QT_UTILITIES_SUPPORT_DBUS_NOTIFICATIONS is defined.

Usage

First create a new instance. The constructor allows to set basic parameters. To set more parameters, use setter methods. Call show() to actually show the notification. This method can also be used to update the currently shown notification (it will not be updated automatically by just using the setter methods).

Instances of this class share static data. So do not call the member functions from different threads without proper synchronization - even if using different instances. The destructor is safe to call, though.

See also: https://developer.gnome.org/notification-spec

Definition at line 22 of file dbusnotification.h.

Member Typedef Documentation

◆ IDType

using QtUtilities::DBusNotification::IDType = uint

Definition at line 34 of file dbusnotification.h.

Constructor & Destructor Documentation

◆ DBusNotification() [1/2]

QtUtilities::DBusNotification::DBusNotification	(	const QString &	title,
		NotificationIcon	icon = NotificationIcon::Information,
		int	timeout = 10000,
		QObject *	parent = nullptr )

explicit

Creates a new notification (which is not shown instantly).

Definition at line 162 of file dbusnotification.cpp.

◆ DBusNotification() [2/2]

QtUtilities::DBusNotification::DBusNotification	(	const QString &	title,
		const QString &	icon,
		int	timeout = 10000,
		QObject *	parent = nullptr )

explicit

Creates a new notification (which is not shown instantly).

Definition at line 176 of file dbusnotification.cpp.

◆ ~DBusNotification()

QtUtilities::DBusNotification::~DBusNotification ( )

override

Closes the notification if still shown and delete the object.

Definition at line 204 of file dbusnotification.cpp.

Member Function Documentation

◆ actionInvoked

void QtUtilities::DBusNotification::actionInvoked ( const QString & action )

signal

Emitted when action has been invoked.

◆ actions()

const QStringList & QtUtilities::DBusNotification::actions ( ) const

inline

Returns the actions for the notification.

The actions are a list of action IDs and action names. The ID is returned by the actionInvoked() signal if an action is triggered. The action name is the user-visible name of the notification.

Example: { QStringLiteral("dismiss"), tr("Dismiss notification"), QStringLiteral("details"), tr("Show details") }

Definition at line 363 of file dbusnotification.h.

◆ applicationName()

const QString & QtUtilities::DBusNotification::applicationName ( ) const

inline

Returns the application name to be used.

Remarks: If the application name is empty (which is the default), QCoreApplication::applicationName() is used instead.

Definition at line 203 of file dbusnotification.h.

◆ category()

QString QtUtilities::DBusNotification::category ( ) const

inline

Returns the category.

See also: https://developer.gnome.org/notification-spec/#categories

Definition at line 339 of file dbusnotification.h.

◆ closed

void QtUtilities::DBusNotification::closed ( NotificationCloseReason reason )

signal

Emitted when the notification has been closed.

◆ deleteOnCloseOrError()

void QtUtilities::DBusNotification::deleteOnCloseOrError ( )

Makes the notification object delete itself when the notification has been closed or an error occurred.

Definition at line 281 of file dbusnotification.cpp.

◆ error

void QtUtilities::DBusNotification::error ( )

signal

Emitted when the notification couldn't be shown.

◆ hide

bool QtUtilities::DBusNotification::hide ( )

slot

Hides the notification (if still visible).

Remarks: On success, the signal closed() is emitted with the reason NotificationCloseReason::Manually.

Definition at line 383 of file dbusnotification.cpp.

◆ hint() [1/2]

QVariant QtUtilities::DBusNotification::hint ( const QString & name ) const

inline

Returns the hint with the specified name.

Definition at line 260 of file dbusnotification.h.

◆ hint() [2/2]

QVariant QtUtilities::DBusNotification::hint	(	const QString &	name,
		const QString &	fallbackNames... ) const

inline

Returns the hint with the specified name.

If no hint is present, the fallbackNames are tried in the specified order.

Definition at line 268 of file dbusnotification.h.

◆ hints() [1/2]

QVariantMap & QtUtilities::DBusNotification::hints ( )

inline

Definition at line 382 of file dbusnotification.h.

◆ hints() [2/2]

const QVariantMap & QtUtilities::DBusNotification::hints ( ) const

inline

Definition at line 377 of file dbusnotification.h.

◆ icon()

const QString & QtUtilities::DBusNotification::icon ( ) const

inline

Returns the icon name.

See also: setIcon() for more details

Definition at line 241 of file dbusnotification.h.

◆ image()

const QImage QtUtilities::DBusNotification::image ( ) const

Returns the image.

See also: setImage() for more details

Definition at line 248 of file dbusnotification.cpp.

◆ imagePath()

const QString QtUtilities::DBusNotification::imagePath ( ) const

inline

Returns the image path.

See also: setImagePath() for more details

Definition at line 278 of file dbusnotification.h.

◆ isAvailable()

bool QtUtilities::DBusNotification::isAvailable ( )

static

Returns whether the notification D-Bus daemon is running.

Definition at line 219 of file dbusnotification.cpp.

◆ isPending()

bool QtUtilities::DBusNotification::isPending ( ) const

Returns whether the notification is about to be shown after calling show() or update() but has not been shown yet.

Remarks: This is the case when show() or update() has been called but the notification daemon has not responded yet. When the notification daemon has responded or an error occurred isPending() will return false again. On success, isVisible() should return true instead.

Definition at line 272 of file dbusnotification.cpp.

◆ isResident()

bool QtUtilities::DBusNotification::isResident ( ) const

inline

Returns whether the notification will remain visible after an action has been clicked.

Definition at line 322 of file dbusnotification.h.

◆ isVisible()

QtUtilities::DBusNotification::isVisible ( ) const

inline

Returns whether the notification is (still) visible.

Definition at line 387 of file dbusnotification.h.

◆ message()

const QString & QtUtilities::DBusNotification::message ( ) const

inline

Definition at line 227 of file dbusnotification.h.

◆ queryCapabilities()

bool QtUtilities::DBusNotification::queryCapabilities ( const std::function< void(Capabilities &&capabilities)> & callback )

static

Definition at line 356 of file dbusnotification.cpp.

◆ setActions()

QtUtilities::DBusNotification::setActions ( const QStringList & actions )

inline

Sets the actions for the notification.

Sets the list of available actions.

See also: see actions() for details and an example

Remarks: The list consists of pairs of action IDs and action labels, eg. QStringList({QStringLiteral("first_id"), tr("First action"), QStringLiteral("second_id"), tr("Second action"), ...})

See also: actionInvoked() signal

Definition at line 372 of file dbusnotification.h.

◆ setApplicationName()

void QtUtilities::DBusNotification::setApplicationName ( const QString & applicationName )

inline

Sets the application name to be used.

Remarks: If the application name is empty (which is the default), QCoreApplication::applicationName() is used instead.

Definition at line 212 of file dbusnotification.h.

◆ setCategory()

void QtUtilities::DBusNotification::setCategory ( const QString & category )

inline

Sets the category.

See also: https://developer.gnome.org/notification-spec/#categories

Definition at line 348 of file dbusnotification.h.

◆ setIcon() [1/2]

void QtUtilities::DBusNotification::setIcon ( const QString & icon )

inline

Sets the icon name.

Remarks: The specified icon should be either an URI (file:// is the only URI schema supported right now) or a name in an icon theme.

Definition at line 252 of file dbusnotification.h.

◆ setIcon() [2/2]

void QtUtilities::DBusNotification::setIcon ( NotificationIcon icon )

Sets the icon to one of the pre-defined notification icons.

Definition at line 228 of file dbusnotification.cpp.

◆ setImage()

void QtUtilities::DBusNotification::setImage ( const QImage & image )

Sets the image.

Remarks: image is a raw data image format which describes the width, height, rowstride, has alpha, bits per sample, channels and image data respectively.

Definition at line 259 of file dbusnotification.cpp.

◆ setImagePath()

void QtUtilities::DBusNotification::setImagePath ( const QString & imagePath )

inline

Sets the image path.

Remarks: Alternative way to define the notification image; setImage() precedes.

Definition at line 288 of file dbusnotification.h.

◆ setMessage()

QtUtilities::DBusNotification::setMessage ( const QString & message )

inline

Sets the message to be shown.

Remarks

Might also be set via show() and update().
Can contain the following HTML tags: <b>, <i>, <u>, <a href="..."> and <img src="..." alt="..."/>

Definition at line 232 of file dbusnotification.h.

◆ setResident()

void QtUtilities::DBusNotification::setResident ( bool resident )

inline

Sets whether the notification will remain visible after an action has been clicked.

Definition at line 330 of file dbusnotification.h.

◆ setTimeout()

QtUtilities::DBusNotification::setTimeout ( int timeout )

inline

Sets the number of milliseconds the notification will be visible after calling show().

Remarks

Set to 0 for non-expiring notifications.
Set to -1 to let the notification daemon decide.

Definition at line 298 of file dbusnotification.h.

◆ setTitle()

void QtUtilities::DBusNotification::setTitle ( const QString & title )

inline

Definition at line 222 of file dbusnotification.h.

◆ setUrgency()

void QtUtilities::DBusNotification::setUrgency ( quint8 urgency )

inline

Sets the urgency level (0 = low, 1 = normal, 2 = critical).

Definition at line 314 of file dbusnotification.h.

◆ show [1/2]

bool QtUtilities::DBusNotification::show ( )

slot

Shows the notification.

Remarks

If called when a previous notification is still shown, the previous notification is updated.
If called when a previous notification is about to be shown (isShowing() returns true) no second notification is spawned immediately. Instead, the previously started notification will be updated once it has been shown to apply changes.

Returns: Returns false is the D-Bus daemon isn't reachable and true otherwise.

Definition at line 296 of file dbusnotification.cpp.

◆ show [2/2]

bool QtUtilities::DBusNotification::show ( const QString & message )

slot

Updates the message and shows/updates the notification.

Remarks: If called when a previous notification is still shown, the previous notification is updated.

Returns: Returns false is the D-Bus daemon isn't reachable and true otherwise. The message is updated in any case.

Definition at line 324 of file dbusnotification.cpp.

◆ shown

void QtUtilities::DBusNotification::shown ( )

signal

Emitted when the notification could be shown successful.

◆ timeout()

int QtUtilities::DBusNotification::timeout ( ) const

inline

Definition at line 293 of file dbusnotification.h.

◆ title()

const QString & QtUtilities::DBusNotification::title ( ) const

inline

Definition at line 217 of file dbusnotification.h.

◆ update

bool QtUtilities::DBusNotification::update ( const QString & line )

slot

Updates the message and shows/updates the notification.

Remarks

If called when a previous notification is still shown, the previous notification is updated. In this case the specified line will be appended to the current message.
If called when no previous notification is still shown, the previous message is completely replaced by line and shown as a new notification.

Returns: Returns false is the D-Bus daemon isn't reachable and true otherwise. The message is updated in any case.

Definition at line 342 of file dbusnotification.cpp.

◆ urgency()

int QtUtilities::DBusNotification::urgency ( ) const

inline

Returns the urgency level (0 = low, 1 = normal, 2 = critical).

Definition at line 306 of file dbusnotification.h.

Property Documentation

◆ actions

QtUtilities::DBusNotification::actions

readwrite

Returns the assigned actions.

See also: setActions() for more details.

Definition at line 29 of file dbusnotification.h.

◆ applicationName

QString QtUtilities::DBusNotification::applicationName

readwrite

Definition at line 24 of file dbusnotification.h.

◆ icon

QString QtUtilities::DBusNotification::icon

readwrite

Definition at line 27 of file dbusnotification.h.

◆ message

QtUtilities::DBusNotification::message

readwrite

Returns the assigned message.

See also: setMessage() for more details.

Definition at line 26 of file dbusnotification.h.

◆ pending

bool QtUtilities::DBusNotification::pending

read

Definition at line 31 of file dbusnotification.h.

◆ timeout

QtUtilities::DBusNotification::timeout

readwrite

Returns the number of milliseconds the notification will be visible after calling show().

See also: setTimeout() for more details.

Definition at line 28 of file dbusnotification.h.

◆ title

QString QtUtilities::DBusNotification::title

readwrite

Definition at line 25 of file dbusnotification.h.

◆ visible

bool QtUtilities::DBusNotification::visible

read

Definition at line 30 of file dbusnotification.h.

The documentation for this class was generated from the following files:

misc/dbusnotification.h
misc/dbusnotification.cpp

Classes

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Typedef Documentation

◆ IDType

Constructor & Destructor Documentation

◆ DBusNotification() [1/2]

◆ DBusNotification() [2/2]

◆ ~DBusNotification()

Member Function Documentation

◆ actionInvoked

◆ actions()

◆ applicationName()

◆ category()

◆ closed

◆ deleteOnCloseOrError()

◆ error

◆ hide

◆ hint() [1/2]

◆ hint() [2/2]

◆ hints() [1/2]

◆ hints() [2/2]

◆ icon()

◆ image()

◆ imagePath()

◆ isAvailable()

◆ isPending()

◆ isResident()

◆ isVisible()

◆ message()

◆ queryCapabilities()

◆ setActions()

◆ setApplicationName()

◆ setCategory()

◆ setIcon() [1/2]

◆ setIcon() [2/2]

◆ setImage()

◆ setImagePath()

◆ setMessage()

◆ setResident()

◆ setTimeout()

◆ setTitle()

◆ setUrgency()

◆ show [1/2]

◆ show [2/2]

◆ shown

◆ timeout()

◆ title()

◆ update

◆ urgency()

Property Documentation

◆ actions

◆ applicationName

◆ icon

◆ message

◆ pending

◆ timeout

◆ title

◆ visible