KNotification

KNotification, in sonic-frameworks-notifications (find_package(KF6Notifications), KF6::Notifications), creates notifications with the same C++ and QML API everywhere:

• on Linux, including SonicDE, following the Desktop Notifications specification (SonicDE's desktop shell shows them)
• on Windows, with SnoreToast
• on Android, with NotificationBuilder
• on macOS, with the system's notification center

This page covers the C++ API. The QML API is described in KNotifications QML types.

#The notifyrc file

To send notifications, your application must provide (and install) an appname.notifyrc file listing all its notification events. In SonicDE, it also lets the user control each event, for example mute it or add a sound, in System Settings → Notifications → Configure for Applications….

Install it as knotifications6/appname.notifyrc in a QStandardPaths::GenericDataLocation directory. On Android, the path is qrc:/knotifications6/.

appname must match QCoreApplication::applicationName or be set with KNotification::setComponentName(); otherwise the notifications aren't shown.

The file has two parts, global information and the individual events:

[Global]
IconName=myicon
Name=Name of Application
Comment=A brief description of the application
DesktopEntry=org.foo.yourapplication.desktop

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

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

IconName=, Name= and Comment= work as in desktop entry files. They show where a notification comes from: in the popup, in the notification history and in the System Settings module. Without Name, Comment is shown instead.

For the notifications to appear in those three places:

• DesktopEntry= must match the application's desktop file name (including the extension).
• The desktop file name must be set with QGuiApplication::setDesktopFileName() or with KAboutData.
• The desktop file must not be hidden: not NoDisplay=true, and not limited to other desktops with OnlyShowIn/NotShowIn.

Each event is a group named [Event/ + event ID + ]. You choose the event ID, and pass it to the KNotification constructor.

Action= decides whether the notification pops up (Popup), plays a sound (Sound) or does nothing (None or empty). With Sound, the event also needs a Sound= key. Combine both with |.

Urgency= decides how the notification is presented: Low, Normal, High or Critical, matching the Urgency enum. In SonicDE, critical notifications are shown even in Do Not Disturb mode, and the user can turn popups for low-urgency notifications off (both are settings in System Settings → Notifications, on by default).

With ECM's KDEInstallDirs, install the file like this:

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

#Basic use from C++

With the notifyrc file installed, sending a notification is as simple as creating a KNotification, setting its text and other properties, and sending the event:

KNotification* notification = new KNotification("eventNameFromNotifyrc");
notification->setText("It just works! 🎉");
notification->sendEvent();

#Reacting to the notification being closed

Applications often need to do something when the user closes the notification, its timeout runs out, or the user clicks one of its action buttons. Use the closed signal:

QObject::connect(
    notification, &KNotification::closed,
    [](){
        qInfo() << "Notification closed!";
    });

#Reacting to an action

Depending on the system, notifications can have actions the user clicks to do something quickly. Add one with addAction(), which returns a KNotificationAction, and connect its activated signal to your code.

This example adds an action that brings a QML application's window to the front:

KNotification* notification = new KNotification("eventNameFromNotifyrc");
notification->setText("You have a new email!");
KNotificationAction* openAction = notification->addAction("Open application");
QObject::connect(
    openAction, &KNotificationAction::activated,
    [&engine](){
        auto window = qobject_cast<QQuickWindow*>(engine.rootObjects().first());
        window->show();
        window->requestActivate();
        window->raise();
    }
);
notification->sendEvent();

#A reply action

Notifications can also let the user type a reply inline, which the application then uses, for example to answer a chat message or an email. Use KNotificationReplyAction:

KNotification* notification = new KNotification("eventNameFromNotifyrc");
notification->setText("Your friend just sent a message!");
auto replyAction = std::make_unique<KNotificationReplyAction>("Reply"); // Button label
replyAction->setPlaceholderText("Reply with...");
QObject::connect(replyAction.get(), &KNotificationReplyAction::replied, [](const QString &text) {
    qInfo() << "You sent the message:" << text;
});
// Needs to be after the QObject::connect call!
notification->setReplyAction(std::move(replyAction));
notification->sendEvent();