workspace/plasma/applets/systemtray/core/task.h

   1 /***************************************************************************
   2  *   task.h                                                                *
   3  *                                                                         *
   4  *   Copyright (C) 2008 Jason Stubbs <jasonbstubbs@gmail.com>              *
   5  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  *                                                                         *
  11  *   This program is distributed in the hope that it will be useful,       *
  12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  14  *   GNU General Public License for more details.                          *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU General Public License     *
  17  *   along with this program; if not, write to the                         *
  18  *   Free Software Foundation, Inc.,                                       *
  19  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA .        *
  20  ***************************************************************************/
  21
  22 #ifndef SYSTEMTRAYTASK_H
  23 #define SYSTEMTRAYTASK_H
  24
  25 #include <QtCore/QObject>
  26
  27 #include <QtGui/QIcon>
  28
  29 class QGraphicsWidget;
  30
  31 namespace Plasma
  32 {
  33     class Applet;
  34 } // namespace Plasma
  35
  36 namespace SystemTray
  37 {
  38
  39 /**
  40  * @short System tray task base class
  41  *
  42  * To support a new system tray protocol, Protocol and this class should
  43  * be subclassed.
  44  **/
  45 class Task : public QObject
  46 {
  47     Q_OBJECT
  48
  49 public:
  50     enum Order { First, Normal, Last };
  51
  52     virtual ~Task();
  53
  54     /**
  55      * Creates a new graphics widget for this task
  56      *
  57      * isEmbeddable() should be checked before creating a new widget.
  58      **/
  59     QGraphicsWidget* widget(Plasma::Applet *host);
  60
  61     /**
  62      * Returns the current list of graphics widgets that have been created
  63      * for this task and have not yet been deleted
  64      **/
  65     QList<QGraphicsWidget*> associatedWidgets() const;
  66
  67     /**
  68      * Returns whether this task can be embeddable
  69      *
  70      * Depending on the protocol, there may be circumstances under which
  71      * a new widget can not be created. isEmbeddable() will return false
  72      * under these circumstances.
  73      **/
  74     virtual bool isEmbeddable() const = 0;
  75
  76     /**
  77      * Returns the name of this task that should be presented to the user
  78      **/
  79     virtual QString name() const = 0;
  80
  81     /**
  82      * Returns a unique identifier for this task
  83      *
  84      * The identifier is valid between restarts and so is safe to save
  85      **/
  86     virtual QString typeId() const = 0;
  87
  88     /**
  89      * Returns an icon that can be associated with this task
  90      *
  91      * The icon returned is not necessarily the same icon that appears
  92      * in the tray icon itself.
  93      **/
  94     virtual QIcon icon() const = 0;
  95
  96     /**
  97      * Returns whether the task is currently hideable by the user or not
  98      */
  99     virtual bool isHideable() const;
 100
 101     /**
 102      * Returns the order this Task should be placed in: first, normal or last
 103      */
 104     Order order() const;
 105
 106     /**
 107      * Sets which order this task should be placed in, relative to other Tasks
 108      *
 109      * @arg order the order to set this Task to
 110      */
 111     void setOrder(Order order);
 112
 113 signals:
 114     /**
 115      * Emitted when something about the task has changed
 116      **/
 117     void changed(SystemTray::Task *task = 0);
 118
 119     /**
 120      * Emitted when the task is about to be destroyed
 121      **/
 122     void destroyed(SystemTray::Task *task = 0);
 123
 124 protected:
 125     Task();
 126
 127     /**
 128      * Called when a new widget is required
 129      *
 130      * Subclasses should implement this to return a graphics widget that
 131      * handles all user interaction with the task. Ownership of the
 132      * created widget is handled automatically so subclasses should not
 133      * delete the created widget.
 134      **/
 135     virtual QGraphicsWidget* createWidget(Plasma::Applet *host) = 0;
 136
 137 private slots:
 138     void widgetDeleted();
 139
 140 private:
 141     class Private;
 142     Private* const d;
 143 };
 144
 145 }
 146
 147
 148 #endif