Qt Utilities  5.12.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
MiscUtils::DBusNotification Class Reference

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

#include <dbusnotification.h>

Inheritance diagram for MiscUtils::DBusNotification:
[legend]
Collaboration diagram for MiscUtils::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...
 
void 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 ()
 Closes the notification if still shown and delete the object. 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...
 
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 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).

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

Definition at line 22 of file dbusnotification.h.

Constructor & Destructor Documentation

◆ DBusNotification() [1/2]

MiscUtils::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 148 of file dbusnotification.cpp.

◆ DBusNotification() [2/2]

MiscUtils::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 162 of file dbusnotification.cpp.

◆ ~DBusNotification()

MiscUtils::DBusNotification::~DBusNotification ( )

Closes the notification if still shown and delete the object.

Definition at line 190 of file dbusnotification.cpp.

Member Function Documentation

◆ actionInvoked

void MiscUtils::DBusNotification::actionInvoked ( const QString &  action)
signal

Emitted when action has been invoked.

◆ actions()

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

◆ closed

void MiscUtils::DBusNotification::closed ( NotificationCloseReason  reason)
signal

Emitted when the notification has been closed.

◆ deleteOnCloseOrError()

void MiscUtils::DBusNotification::deleteOnCloseOrError ( )

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

Definition at line 251 of file dbusnotification.cpp.

◆ error

void MiscUtils::DBusNotification::error ( )
signal

Emitted when the notification couldn't be shown.

◆ hide

void MiscUtils::DBusNotification::hide ( )
slot

Hides the notification (if still visible).

Remarks
On success, the signal closed() is emitted with the reason NotificationCloseReason::Manually.
Todo:
Add return value in v6.

Definition at line 345 of file dbusnotification.cpp.

◆ hint() [1/2]

QVariant MiscUtils::DBusNotification::hint ( const QString &  name) const
inline

Returns the hint with the specified name.

Definition at line 225 of file dbusnotification.h.

◆ hint() [2/2]

QVariant MiscUtils::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 233 of file dbusnotification.h.

◆ hints() [1/2]

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

Definition at line 292 of file dbusnotification.h.

◆ hints() [2/2]

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

Definition at line 297 of file dbusnotification.h.

◆ icon()

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

◆ image()

const QImage MiscUtils::DBusNotification::image ( ) const

Returns the image.

See also
setImage() for more details

Definition at line 231 of file dbusnotification.cpp.

◆ imagePath()

const QString MiscUtils::DBusNotification::imagePath ( ) const
inline

Returns the image path.

See also
setImagePath() for more details

Definition at line 243 of file dbusnotification.h.

◆ isAvailable()

bool MiscUtils::DBusNotification::isAvailable ( )
static

Returns whether the notification D-Bus daemon is running.

Definition at line 202 of file dbusnotification.cpp.

◆ isVisible()

MiscUtils::DBusNotification::isVisible ( ) const
inline

Returns whether the notification is (still) visible.

Definition at line 302 of file dbusnotification.h.

◆ message()

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

◆ queryCapabilities()

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

Definition at line 317 of file dbusnotification.cpp.

◆ setActions()

MiscUtils::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 287 of file dbusnotification.h.

◆ setIcon() [1/2]

void MiscUtils::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 217 of file dbusnotification.h.

◆ setIcon() [2/2]

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

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

Definition at line 211 of file dbusnotification.cpp.

◆ setImage()

void MiscUtils::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 242 of file dbusnotification.cpp.

◆ setImagePath()

void MiscUtils::DBusNotification::setImagePath ( const QString &  imagePath)
inline

Sets the image path.

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

Definition at line 253 of file dbusnotification.h.

◆ setMessage()

MiscUtils::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 197 of file dbusnotification.h.

◆ setTimeout()

MiscUtils::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 263 of file dbusnotification.h.

◆ setTitle()

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

Definition at line 187 of file dbusnotification.h.

◆ show [1/2]

bool MiscUtils::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 264 of file dbusnotification.cpp.

◆ show [2/2]

bool MiscUtils::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 285 of file dbusnotification.cpp.

◆ shown

void MiscUtils::DBusNotification::shown ( )
signal

Emitted when the notification could be shown successful.

◆ timeout()

int MiscUtils::DBusNotification::timeout ( ) const

◆ title()

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

◆ update

bool MiscUtils::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 303 of file dbusnotification.cpp.

Property Documentation

◆ actions

MiscUtils::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 28 of file dbusnotification.h.

◆ icon

const QString & MiscUtils::DBusNotification::icon
inlinereadwrite

Returns the icon name.

See also
setIcon() for more details

Definition at line 26 of file dbusnotification.h.

◆ message

MiscUtils::DBusNotification::message
inlinereadwrite

Returns the assigned message.

See also
setMessage() for more details.

Definition at line 25 of file dbusnotification.h.

◆ timeout

MiscUtils::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 27 of file dbusnotification.h.

◆ title

const QString & MiscUtils::DBusNotification::title
inlinereadwrite

Definition at line 24 of file dbusnotification.h.

◆ visible

bool MiscUtils::DBusNotification::visible
read

Definition at line 29 of file dbusnotification.h.


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