plasma/wallpaper.h

   1 /*
   2  *   Copyright 2008 by Aaron Seigo <aseigo@kde.org>
   3  *   Copyright 2008 by Petri Damsten <damu@iki.fi>
   4
   5  *   This program is free software; you can redistribute it and/or modify
   6  *   it under the terms of the GNU Library General Public License as
   7  *   published by the Free Software Foundation; either version 2, or
   8  *   (at your option) 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 Library General Public
  16  *   License along with this program; if not, write to the
  17  *   Free Software Foundation, Inc.,
  18  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  19  */
  20
  21 #ifndef PLASMA_WALLPAPER_H
  22 #define PLASMA_WALLPAPER_H
  23
  24 #include <kplugininfo.h>
  25
  26 #include <plasma/plasma.h>
  27 #include <plasma/version.h>
  28
  29 namespace Plasma
  30 {
  31 class WallpaperPrivate;
  32
  33 /**
  34  * @class Wallpaper plasma/wallpaper.h <Plasma/Wallpaper>
  35  *
  36  * @short The base Wallpaper class
  37  *
  38  * "Wallpapers" are components that paint the background for Containments that
  39  * do not provide their own background rendering.
  40  *
  41  * Wallpaper plugins are registered using .desktop files. These files should be
  42  * named using the following naming scheme:
  43  *
  44  *     plasma-wallpaper-\<pluginname\>.desktop
  45  *
  46  * If a wallpaper plugin provides more than on mode (e.g. Single Image, Wallpaper)
  47  * it should include a Actions= entry in the .desktop file, listing the possible
  48  * actions. An actions group should be included to provide for translatable names.
  49  */
  50
  51 class PLASMA_EXPORT Wallpaper : public QObject
  52 {
  53     Q_OBJECT
  54     Q_PROPERTY(QRectF boundingRect READ boundingRect WRITE setBoundingRect)
  55     Q_PROPERTY(QString name READ name)
  56     Q_PROPERTY(QString pluginName READ pluginName)
  57     Q_PROPERTY(QString icon READ icon)
  58     Q_PROPERTY(KServiceAction renderingMode READ renderingMode)
  59     Q_PROPERTY(QList<KServiceAction> listRenderingModes READ listRenderingModes)
  60
  61     public:
  62         ~Wallpaper();
  63
  64         /**
  65          * Returns a list of all known wallpapers.
  66          *
  67          * @return list of wallpapers
  68          **/
  69         static KPluginInfo::List listWallpaperInfo(const QString &formFactor = QString());
  70
  71         /**
  72          * Attempts to load an wallpaper
  73          *
  74          * Returns a pointer to the wallpaper if successful.
  75          * The caller takes responsibility for the wallpaper, including
  76          * deleting it when no longer needed.
  77          *
  78          * @param name the plugin name, as returned by KPluginInfo::pluginName()
  79          * @param args to send the wallpaper extra arguments
  80          * @return a pointer to the loaded wallpaper, or 0 on load failure
  81          **/
  82         static Wallpaper *load(const QString &name, const QVariantList &args = QVariantList());
  83
  84         /**
  85          * Attempts to load an wallpaper
  86          *
  87          * Returns a pointer to the wallpaper if successful.
  88          * The caller takes responsibility for the wallpaper, including
  89          * deleting it when no longer needed.
  90          *
  91          * @param info KPluginInfo object for the desired wallpaper
  92          * @param args to send the wallpaper extra arguments
  93          * @return a pointer to the loaded wallpaper, or 0 on load failure
  94          **/
  95         static Wallpaper *load(const KPluginInfo &info, const QVariantList &args = QVariantList());
  96
  97         /**
  98          * Returns the user-visible name for the wallpaper, as specified in the
  99          * .desktop file.
 100          *
 101          * @return the user-visible name for the wallpaper.
 102          **/
 103         QString name() const;
 104
 105         /**
 106          * Returns the plugin name for the wallpaper
 107          */
 108         QString pluginName() const;
 109
 110         /**
 111          * Returns the icon related to this wallpaper
 112          **/
 113         QString icon() const;
 114
 115         /**
 116          * @return the currently active rendering mode
 117          */
 118         KServiceAction renderingMode() const;
 119
 120
 121         /**
 122          * Sets the rendering mode for this wallpaper.
 123          * @param mode One of the modes supported by the plugin,
 124          *             or an empty string for the default mode.
 125          */
 126         void setRenderingMode(const QString &mode);
 127
 128         /**
 129          * Returns modes the wallpaper has, as specified in the
 130          * .desktop file.
 131          */
 132         QList<KServiceAction> listRenderingModes() const;
 133
 134         /**
 135          * @return true if initialized (usually by calling retore), false otherwise
 136          */
 137         bool isInitialized() const;
 138
 139         /**
 140          * Returns bounding rectangle
 141          */
 142         QRectF boundingRect() const;
 143
 144         /**
 145          * Sets bounding rectangle
 146          */
 147         void setBoundingRect(const QRectF &boundingRect);
 148
 149        /**
 150          * This method is called when the wallpaper should be painted.
 151          *
 152          * @param painter the QPainter to use to do the painting
 153          * @param exposedRect the rect to paint within
 154          **/
 155         virtual void paint(QPainter *painter, const QRectF &exposedRect) = 0;
 156
 157         /**
 158          * This method should be called once the wallpaper is loaded or mode is changed.
 159          * @param config Config group to load settings
 160          * @see init
 161          **/
 162         void restore(const KConfigGroup &config);
 163
 164         /**
 165          * This method is called when settings need to be saved.
 166          * @param config Config group to save settings
 167          **/
 168         virtual void save(KConfigGroup &config);
 169
 170         /**
 171          * Returns widget for configuration dialog.
 172          */
 173         virtual QWidget *createConfigurationInterface(QWidget *parent);
 174
 175         /**
 176          * Mouse move event. To prevent further propagation of the event,
 177          * the event must be accepted.
 178          *
 179          * @param event the mouse event object
 180          */
 181         virtual void mouseMoveEvent(QGraphicsSceneMouseEvent *event);
 182
 183         /**
 184          * Mouse press event. To prevent further propagation of the even,
 185          * and to receive mouseMoveEvents, the event must be accepted.
 186          *
 187          * @param event the mouse event object
 188          */
 189         virtual void mousePressEvent(QGraphicsSceneMouseEvent *event);
 190
 191         /**
 192          * Mouse release event. To prevent further propagation of the event,
 193          * the event must be accepted.
 194          *
 195          * @param event the mouse event object
 196          */
 197         virtual void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);
 198
 199         /**
 200          * Mouse wheel event. To prevent further propagation of the event,
 201          * the event must be accepted.
 202          *
 203          * @param event the wheel event object
 204          */
 205         virtual void wheelEvent(QGraphicsSceneWheelEvent *event);
 206
 207     Q_SIGNALS:
 208         /**
 209          * This signal indicates that wallpaper needs to be repainted.
 210          */
 211         void update(const QRectF &exposedArea);
 212
 213     protected:
 214         /**
 215          * This constructor is to be used with the plugin loading systems
 216          * found in KPluginInfo and KService. The argument list is expected
 217          * to have one element: the KService service ID for the desktop entry.
 218          *
 219          * @param parent a QObject parent; you probably want to pass in 0
 220          * @param args a list of strings containing one entry: the service id
 221          */
 222         Wallpaper(QObject *parent, const QVariantList &args);
 223
 224         /**
 225          * This method is called once the wallpaper is loaded or mode is changed.
 226          *
 227          * The mode can be retrieved using the renderMode() method.
 228          *
 229          * @param config Config group to load settings
 230          **/
 231         virtual void init(const KConfigGroup &config);
 232
 233     private:
 234         WallpaperPrivate *const d;
 235 };
 236
 237 } // Plasma namespace
 238
 239 /**
 240  * Register an wallpaper when it is contained in a loadable module
 241  */
 242 #define K_EXPORT_PLASMA_WALLPAPER(libname, classname) \
 243 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 244 K_EXPORT_PLUGIN(factory("plasma_wallpaper_" #libname)) \
 245 K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
 246
 247 #endif // multiple inclusion guard