1 /*
2     SPDX-FileCopyrightText: 2005-2006 Olivier Goffart <ogoffart at kde.org>
3 
4     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #ifndef KNOTIFICATIONPLUGIN_H
8 #define KNOTIFICATIONPLUGIN_H
9 
10 #include <QObject>
11 #include <QTextDocumentFragment>
12 
13 #include <KPluginFactory>
14 
15 #include "knotifications_export.h"
16 
17 class KNotification;
18 class KNotificationPluginPrivate;
19 class KNotifyConfig;
20 
21 /**
22  * @class KNotificationPlugin knotificationplugin.h KNotificationPlugin
23  *
24  * @brief abstract class for KNotification actions
25  *
26  * A KNotificationPlugin is responsible of notification presentation.
27  * You can subclass it to have your own presentation of a notification.
28  *
29  * You should reimplement the KNotificationPlugin::notify method to display the notification.
30  *
31  * @author Olivier Goffart <ogoffart at kde.org>
32  */
33 class KNOTIFICATIONS_EXPORT KNotificationPlugin : public QObject
34 {
35     Q_OBJECT
36 
37 public:
38     KNotificationPlugin(QObject *parent = nullptr, const QVariantList &args = QVariantList());
39     ~KNotificationPlugin() override;
40 
41     /**
42      * @brief return the name of this plugin.
43      *
44      * this is the name that should appear in the .notifyrc file,
45      * in the field Action=... if a notification is set to use this plugin
46      */
47     virtual QString optionName() = 0;
48 
49     // TODO KF6 make notifyConfig const reference
50     /**
51      * This function is called when the notification is sent.
52      * (or re-sent)
53      * You should implement this function to display a notification
54      *
55      * for each call to this function (even for re-notification), you MUST call finish(KNotification*)
56      *
57      * @param notification is the KNotification object
58      * @param notifyConfig is the configuration of the notification
59      */
60     virtual void notify(KNotification *notification, KNotifyConfig *notifyConfig) = 0;
61 
62     // TODO KF6 make config const reference
63     /**
64      * This function is called when the notification has changed (such as the text or the icon)
65      */
66     virtual void update(KNotification *notification, KNotifyConfig *config);
67 
68     /**
69      * This function is called when the notification has been closed
70      */
71     virtual void close(KNotification *notification);
72 
73 protected:
74     /**
75      * emit the finished signal
76      * you MUST call this function for each call to notify(), even if you do nothing there
77      *
78      * call it when the presentation is finished (because the user closed the popup or the sound is finished)
79      *
80      * If your presentation is synchronous, you can even call this function from the notify() call itself
81      */
82     void finish(KNotification *notification);
83 
stripRichText(const QString & s)84     static inline QString stripRichText(const QString &s)
85     {
86         return QTextDocumentFragment::fromHtml(s).toPlainText();
87     }
88 
89 Q_SIGNALS:
90     /**
91      * the presentation is finished.
92      */
93     void finished(KNotification *notification);
94     /**
95      * emit this signal if one action was invoked
96      * @param id is the id of the notification
97      * @param action is the action number.  zero for the default action
98      */
99     void actionInvoked(int id, int action);
100 
101     void replied(int id, const QString &text);
102 
103 private:
104     KNotificationPluginPrivate *const d;
105 };
106 
107 #endif
108