KNotifications

KNotifications is a cross-platform library for creating popup notifications.

It currently supports Linux (and other Unix platforms that implement freedesktop.org notifications), Windows (8 or later), macOS and Android (version 5.0 or later).

Please consult the KDE Human Interface Guidelines for when using Notifications is appropriate.

KNotification is the main entry point for using KNotifications.

The global config file

In order to perform a notification, you need to create a description file, which contains default parameters of the notification. It needs to be installed to knotifications6/appname.notifyrc in a QStandardPaths::GenericDataLocation directory. On Android, this path is qrc:/knotifications6/.

The filename must either match QCoreApplication::applicationName or be specified as the component name to the KNotification object. Notifications won't be visible otherwise.

You can do this with the following CMake command, if you use ECM's KDEInstallDirs:

install(FILES appname.notifyrc  DESTINATION ${KDE_INSTALL_KNOTIFYRCDIR})

This file contains mainly 2 parts, global information and individual events

Global information

The global part looks like that

[Global]
IconName=myicon
Name=Name of Application
Comment=A brief description of the application
DesktopEntry=DesktopFileName

The icon filename is just the name, without extension. It follows the same behavior as `Icon=` as defined in the Freedesktop Desktop Entry specification. The Name field may be used as the application name for popup, it may also be used to visualize the application's notification settings in KCModule instances. If Name is not present, Comment is used instead. Either must be present.

The DesktopEntry field is required in order for the application to be listed in the notifications KCModule, and for its notifications to appear in the notification history. Ensure that its value matches the application's desktop file name, that the desktop file name is set in the QGuiApplication or KAboutData desktopFileName property, and that the desktop file is not marked as Hidden.

Definition of Events

The definition of the events forms the most important part of the config file

[Event/newmail]
Name=New E-Mail
Comment=You have got a new email
Action=Sound|Popup

[Event/contactOnline]
Name=Contact Goes Online
Comment=One of your contact has been connected
Sound=filetoplay.ogg
Action=None
Urgency=Low

These are the default settings for each notifiable event. Action is the string representing the action. At the time of writing, the following actions are available: Sound, Popup. Actions can be combined by separating them with '|'.

Urgency can be any of: Low, Normal, Critical.

Example Code

This portion of code will fire the event for the "contactOnline" event

KNotification *notification = new KNotification("contactOnline");
notification->setText(i18n("The contact <i>%1</i> has gone online", contact->name());
notification->setPixmap(contact->pixmap());
notification->setActions({i18n("Open chat")});

connect(notification, QOverload<unsigned int>::of(&KNotification::activated), contact, &Contact::slotOpenChat);

notification->sendEvent();
// Note: notification autodeletes itself with deleteLater() when no longer needed

Using the Module

Using a KDE module's C++ API requires linking against the module library. The preferred way of consuming the library is through CMake.

Building with CMake

Use the find_package() command to locate the needed module component in the KF6 package:

find_package(KF6 REQUIRED COMPONENTS Notifications)
target_link_libraries(mytarget PRIVATE KF6::Notifications)

For more details, see the Build with CMake overview.

Contents