wallpaper.h

Go to the documentation of this file.

/*
 *   Copyright 2008 by Aaron Seigo <aseigo@kde.org>
 *   Copyright 2008 by Petri Damsten <damu@iki.fi>

 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU Library General Public License as
 *   published by the Free Software Foundation; either version 2, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the
 *   Free Software Foundation, Inc.,
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef PLASMA_WALLPAPER_H
#define PLASMA_WALLPAPER_H

#include <kmimetype.h>
#include <kplugininfo.h>

#include <plasma/plasma.h>
#include <plasma/packagestructure.h>
#include <plasma/version.h>

namespace Plasma
{

class DataEngine;
class WallpaperPrivate;
class Package;

class PLASMA_EXPORT Wallpaper : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QRectF boundingRect READ boundingRect WRITE setBoundingRect)
    Q_PROPERTY(QString name READ name)
    Q_PROPERTY(QString pluginName READ pluginName)
    Q_PROPERTY(QString icon READ icon)
    Q_PROPERTY(KServiceAction renderingMode READ renderingMode)
    Q_PROPERTY(QList<KServiceAction> listRenderingModes READ listRenderingModes)
    Q_PROPERTY(bool usingRenderingCache READ isUsingRenderingCache WRITE setUsingRenderingCache)
    Q_PROPERTY(bool previewing READ isPreviewing WRITE setPreviewing)
    Q_PROPERTY(ResizeMethod resizeMethod READ resizeMethodHint WRITE setResizeMethodHint)
    Q_PROPERTY(QSizeF targetSize READ targetSizeHint WRITE setTargetSizeHint)

    public:
        enum ResizeMethod {
            ScaledResize ,
            CenteredResize ,
            ScaledAndCroppedResize ,
            TiledResize ,
            CenterTiledResize ,
            MaxpectResize ,
            LastResizeMethod = MaxpectResize
        };
        Q_ENUMS(ResizeMethod)

        
        explicit Wallpaper(QObject * parent = 0);

        ~Wallpaper();

        void setUrls(const KUrl::List &urls);


        static KPluginInfo::List listWallpaperInfo(const QString &formFactor = QString());

        static KPluginInfo::List listWallpaperInfoForMimetype(const QString &mimetype,
                                                              const QString &formFactor = QString());

        static Wallpaper *load(const QString &name, const QVariantList &args = QVariantList());

        static Wallpaper *load(const KPluginInfo &info, const QVariantList &args = QVariantList());

        static PackageStructure::Ptr packageStructure(Wallpaper *paper = 0);

        QString name() const;

        const Package *package() const;

        QString pluginName() const;

        QString icon() const;

        KServiceAction renderingMode() const;

        bool supportsMimetype(const QString &mimetype) const;

        void setRenderingMode(const QString &mode);

        QList<KServiceAction> listRenderingModes() const;

        bool isInitialized() const;

        QRectF boundingRect() const;

        void setBoundingRect(const QRectF &boundingRect);

        virtual void paint(QPainter *painter, const QRectF &exposedRect) = 0;

        void restore(const KConfigGroup &config);

        virtual void save(KConfigGroup &config);

        virtual QWidget *createConfigurationInterface(QWidget *parent);

        virtual void mouseMoveEvent(QGraphicsSceneMouseEvent *event);

        virtual void mousePressEvent(QGraphicsSceneMouseEvent *event);

        virtual void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);

        virtual void wheelEvent(QGraphicsSceneWheelEvent *event);

        Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;

        bool configurationRequired() const;

        bool isUsingRenderingCache() const;

        void setResizeMethodHint(Wallpaper::ResizeMethod resizeMethod);

        Wallpaper::ResizeMethod resizeMethodHint() const;

        void setTargetSizeHint(const QSizeF &targetSize);

        QSizeF targetSizeHint() const;

        QList<QAction*> contextualActions() const;

        bool isPreviewing() const;

        void setPreviewing(bool previewing);

        bool needsPreviewDuringConfiguration() const;


    Q_SIGNALS:
        void update(const QRectF &exposedArea);

        void configureRequested();

        void configurationRequired(bool needsConfig);

        void configNeedsSaving();

        void renderCompleted(const QImage &image);

        KDE_DEPRECATED void urlDropped(const KUrl &url);

        void renderHintsChanged();

    protected Q_SLOTS:
        void addUrls(const KUrl::List &urls);

    protected:
        Wallpaper(QObject *parent, const QVariantList &args);

        virtual void init(const KConfigGroup &config);

        void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());

        void render(const QString &sourceImagePath, const QSize &size,
                    Wallpaper::ResizeMethod resizeMethod = ScaledResize,
                    const QColor &color = QColor(0, 0, 0));

        void render(const QImage &image, const QSize &size,
                    Wallpaper::ResizeMethod resizeMethod = ScaledResize,
                    const QColor &color = QColor(0, 0, 0));

        void setUsingRenderingCache(bool useCache);

        bool findInCache(const QString &key, QImage &image, unsigned int lastModified = 0);

        void insertIntoCache(const QString& key, const QImage &image);

        void setContextualActions(const QList<QAction*> &actions);

        //FIXME: KDE5, this must be moved to the dptr
        QList<QAction*> contextActions;

        void setPreviewDuringConfiguration(const bool preview);

    private:
        Q_PRIVATE_SLOT(d, void newRenderCompleted(const WallpaperRenderRequest &request,
                                                  const QImage &image))
        Q_PRIVATE_SLOT(d, void initScript())

        friend class WallpaperPackage;
        friend class WallpaperPrivate;
        friend class WallpaperScript;
        friend class WallpaperWithPaint;
        friend class ContainmentPrivate;
        WallpaperPrivate *const d;
};

} // Plasma namespace

#define K_EXPORT_PLASMA_WALLPAPER(libname, classname) \
K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
K_EXPORT_PLUGIN(factory("plasma_wallpaper_" #libname)) \
K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)

#endif // multiple inclusion guard