Qt Utilities  6.0.2
Common Qt related C++ classes and routines used by my applications such as dialogs, widgets and models
Classes | 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 Slots

bool show ()
 Shows the notification. More...
 
bool show (const QString &message)
 Updates the message and shows/updates the notification. More...
 
bool update (const QString &line)
 Updates the message and shows/updates the notification. More...
 
bool hide ()
 Hides the notification (if still visible). More...
 

Signals

void shown ()
 Emitted when the notification could be shown successful. More...
 
void error ()
 Emitted when the notification couldn't be shown. More...
 
void closed (NotificationCloseReason reason)
 Emitted when the notification has been closed. More...
 
void actionInvoked (const QString &action)
 Emitted when action has been invoked. More...
 

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). More...
 
 DBusNotification (const QString &title, const QString &icon, int timeout=10000, QObject *parent=nullptr)
 Creates a new notification (which is not shown instantly). More...
 
 ~DBusNotification () override
 Closes the notification if still shown and delete the object. More...
 
const QString & applicationName () const
 
void setApplicationName (const QString &applicationName)
 Sets the application name to be used. More...
 
const QString & title () const
 
void setTitle (const QString &title)
 
const QString & message () const
 
void setMessage (const QString &message)
 Sets the message to be shown. More...
 
const QString & icon () const
 
void setIcon (const QString &icon)
 Sets the icon name. More...
 
void setIcon (NotificationIcon icon)
 Sets the icon to one of the pre-defined notification icons. More...
 
const QImage image () const
 Returns the image. More...
 
void setImage (const QImage &image)
 Sets the image. More...
 
const QString imagePath () const
 Returns the image path. More...
 
void setImagePath (const QString &imagePath)
 Sets the image path. More...
 
int timeout () const
 
void setTimeout (int timeout)
 Sets the number of milliseconds the notification will be visible after calling show(). More...
 
int urgency () const
 Returns the urgency level (0 = low, 1 = normal, 2 = critical). More...
 
void setUrgency (quint8 urgency)
 Sets the urgency level (0 = low, 1 = normal, 2 = critical). More...
 
bool isResident () const
 Returns whether the notification will remain visible after an action has been clicked. More...
 
void setResident (bool resident)
 Sets whether the notification will remain visible after an action has been clicked. More...
 
QString category () const
 Returns the category. More...
 
void setCategory (const QString &category)
 Sets the category. More...
 
const QStringList & actions () const
 
void setActions (const QStringList &actions)
 Sets the actions for the notification. More...
 
const QVariantMap & hints () const
 
QVariantMap & hints ()
 
QVariant hint (const QString &name) const
 Returns the hint with the specified name. More...
 
QVariant hint (const QString &name, const QString &fallbackNames...) const
 Returns the hint with the specified name. More...
 
bool isVisible () const
 Returns whether the notification is (still) visible. More...
 
void deleteOnCloseOrError ()
 Makes the notification object delete itself when the notification has been closed or an error occurred. More...
 

Static Public Member Functions

static bool isAvailable ()
 Returns whether the notification D-Bus daemon is running. More...
 
static bool queryCapabilities (const std::function< void(Capabilities &&capabilities)> &callback)
 

Properties

QString applicationName
 Returns the application name to be used. More...
 
QString title
 
QString message
 Returns the assigned message. More...
 
QString icon
 Returns the icon name. More...
 
int timeout
 Returns the number of milliseconds the notification will be visible after calling show(). More...
 
QStringList actions
 Returns the actions for the notification. More...
 
bool visible
 

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.

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 155 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 169 of file dbusnotification.cpp.

◆ ~DBusNotification()

QtUtilities::DBusNotification::~DBusNotification ( )
override

Closes the notification if still shown and delete the object.

Definition at line 197 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

◆ applicationName()

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

◆ category()

QString QtUtilities::DBusNotification::category ( ) const
inline

Returns the category.

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

Definition at line 332 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 261 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 356 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 253 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 261 of file dbusnotification.h.

◆ hints() [1/2]

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

Definition at line 375 of file dbusnotification.h.

◆ hints() [2/2]

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

Definition at line 370 of file dbusnotification.h.

◆ icon()

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

◆ image()

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

Returns the image.

See also
setImage() for more details

Definition at line 241 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 271 of file dbusnotification.h.

◆ isAvailable()

bool QtUtilities::DBusNotification::isAvailable ( )
static

Returns whether the notification D-Bus daemon is running.

Definition at line 212 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 315 of file dbusnotification.h.

◆ isVisible()

QtUtilities::DBusNotification::isVisible ( ) const
inline

Returns whether the notification is (still) visible.

Definition at line 380 of file dbusnotification.h.

◆ message()

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

◆ queryCapabilities()

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

Definition at line 329 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 365 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 205 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 341 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 245 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 221 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 252 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 281 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 225 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 323 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 291 of file dbusnotification.h.

◆ setTitle()

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

Definition at line 215 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 307 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.
Returns
Returns false is the D-Bus daemon isn't reachable and true otherwise.

Definition at line 274 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 297 of file dbusnotification.cpp.

◆ shown

void QtUtilities::DBusNotification::shown ( )
signal

Emitted when the notification could be shown successful.

◆ timeout()

int QtUtilities::DBusNotification::timeout ( ) const

◆ title()

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

◆ 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 315 of file dbusnotification.cpp.

◆ urgency()

int QtUtilities::DBusNotification::urgency ( ) const
inline

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

Definition at line 299 of file dbusnotification.h.

Property Documentation

◆ actions

QtUtilities::DBusNotification::actions
inlinereadwrite

Returns the actions for the notification.

Returns the assigned actions.

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") }

See also
setActions() for more details.

Definition at line 29 of file dbusnotification.h.

◆ applicationName

const QString & QtUtilities::DBusNotification::applicationName
inlinereadwrite

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 24 of file dbusnotification.h.

◆ icon

const QString & QtUtilities::DBusNotification::icon
inlinereadwrite

Returns the icon name.

See also
setIcon() for more details

Definition at line 27 of file dbusnotification.h.

◆ message

QtUtilities::DBusNotification::message
inlinereadwrite

Returns the assigned message.

See also
setMessage() for more details.

Definition at line 26 of file dbusnotification.h.

◆ timeout

QtUtilities::DBusNotification::timeout
inlinereadwrite

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

const QString & QtUtilities::DBusNotification::title
inlinereadwrite

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: