runtime/knotify/knotifyplugin.h

   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
  28 class KNotifyConfig;
  29
  30
  31 /**
  32  * @brief abstract class for KNotify actions
  33  *
  34  * A KNotifyPlugin is responsible of one presentation.  You can subclass it to have your own knotify presentation.
  35  *
  36  * You should reimplement the KNotifyPlugin::notify method to display the notification.
  37  *
  38  * Dynamic plugin support is not yet implemented in KNotify.
  39  * In order to load your plugin you need to add a line to KNotify::loadConfig() in knotify.cpp
  40  *
  41  * @author Olivier Goffart <ogoffart at kde.org>
  42 */
  43 class KNotifyPlugin : public QObject
  44 { Q_OBJECT
  45         public:
  46                 KNotifyPlugin(QObject *parent=0l);
  47                 virtual ~KNotifyPlugin();
  48
  49                 /**
  50                  * @brief return the name of this plugin.
  51                  *
  52                  * this is the name that should appears in the .knotifyrc file,
  53                  * in the field Action=... if a notification
  54                  */
  55                 virtual QString optionName() =0;
  56                 /**
  57                  * This function is called when the notification is sent.
  58                  * (or re-sent)
  59                  * You should implement this function to display a notification
  60                  *
  61                  * for each call to this function (even for re-notification), you MUST call finish(int)
  62                  *
  63                  * @param id is the notification id
  64                  * @param config is the configuration of the notification
  65                  */
  66                 virtual void notify(int id , KNotifyConfig *config )=0;
  67
  68                 /**
  69                  * This function is called when the notification has changed (such as the text or the icon)
  70                  */
  71                 virtual void update(int /*id*/, KNotifyConfig * /*config*/) {}
  72
  73                 /**
  74                  * This function is called when the notification has been closed
  75                  */
  76                 virtual void close(int id) { emit finished(id);}
  77
  78         protected:
  79                 /**
  80                  * emit the finished signal
  81                  * you MUST call this function for each call to notify(), even if you do nothing there
  82                  *
  83                  * call it when the presentation is finished (because the user closed the popup or the sound is finished)
  84                  *
  85                  * If your presentation is syncronious, you can even call this function from the notify() call itself
  86                  */
  87                 void finish(int id) { emit finished(id); }
  88
  89         Q_SIGNALS:
  90                 /**
  91                  * the presentation is finished.
  92                  */
  93                 void finished(int id);
  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
 102 #endif