1/*
2 Copyright (C) 2005-2006 by Olivier Goffart <ogoffart at kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), which shall
10 act as a proxy defined in Section 6 of version 3 of the license.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License along with this library. If not, see <http://www.gnu.org/licenses/>.
19
20 */
21
22#ifndef KNOTIFICATIONPLUGIN_H
23#define KNOTIFICATIONPLUGIN_H
24
25#include <QObject>
26#include <KPluginFactory>
27
28#include "knotifications_export.h"
29
30class KNotification;
31class KNotificationPluginPrivate;
32class KNotifyConfig;
33
34/**
35 * @class KNotificationPlugin knotificationplugin.h KNotificationPlugin
36 *
37 * @brief abstract class for KNotification actions
38 *
39 * A KNotificationPlugin is responsible of notification presentation.
40 * You can subclass it to have your own presentation of a notification.
41 *
42 * You should reimplement the KNotificationPlugin::notify method to display the notification.
43 *
44 * @author Olivier Goffart <ogoffart at kde.org>
45*/
46class KNOTIFICATIONS_EXPORT KNotificationPlugin : public QObject
47{
48 Q_OBJECT
49
50public:
51 KNotificationPlugin(QObject *parent = nullptr, const QVariantList &args = QVariantList());
52 virtual ~KNotificationPlugin();
53
54 /**
55 * @brief return the name of this plugin.
56 *
57 * this is the name that should appear in the .notifyrc file,
58 * in the field Action=... if a notification is set to use this plugin
59 */
60 virtual QString optionName() = 0;
61
62 // TODO KF6 make notifyConfig const reference
63 /**
64 * This function is called when the notification is sent.
65 * (or re-sent)
66 * You should implement this function to display a notification
67 *
68 * for each call to this function (even for re-notification), you MUST call finish(KNotification*)
69 *
70 * @param notification is the KNotification object
71 * @param notifyConfig is the configuration of the notification
72 */
73 virtual void notify(KNotification *notification, KNotifyConfig *notifyConfig) = 0;
74
75 // TODO KF6 make config const reference
76 /**
77 * This function is called when the notification has changed (such as the text or the icon)
78 */
79 virtual void update(KNotification *notification, KNotifyConfig *config);
80
81 /**
82 * This function is called when the notification has been closed
83 */
84 virtual void close(KNotification *notification);
85
86protected:
87 /**
88 * emit the finished signal
89 * you MUST call this function for each call to notify(), even if you do nothing there
90 *
91 * call it when the presentation is finished (because the user closed the popup or the sound is finished)
92 *
93 * If your presentation is synchronous, you can even call this function from the notify() call itself
94 */
95 void finish(KNotification *notification);
96
97Q_SIGNALS:
98 /**
99 * the presentation is finished.
100 */
101 void finished(KNotification *notification);
102 /**
103 * emit this signal if one action was invoked
104 * @param id is the id of the notification
105 * @param action is the action number. zero for the default action
106 */
107 void actionInvoked(int id , int action);
108
109private:
110 KNotificationPluginPrivate *const d;
111
112};
113
114#endif
115