Qt Utilities: QtUtilities::DBusNotification Class Reference

Qt Utilities 6.19.1 Common Qt related C++ classes and routines used by my applications such as dialogs, widgets and models

Loading...
Searching...
No Matches
Classes | Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Properties | List of all members
QtUtilities::DBusNotification Class Reference

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

`#include <dbusnotification.h>`

Inheritance diagram for QtUtilities::DBusNotification:
[legend]
Collaboration diagram for QtUtilities::DBusNotification:
[legend]

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

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

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

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

void 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

QStringList 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

QString 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

int 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