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