From 04f8e295b7573dd691a0d88920503534d013ee08 Mon Sep 17 00:00:00 2001
From: "Aaron J. Seigo" <aseigo@kde.org>
Date: Thu, 2 Apr 2009 04:15:50 +0000
Subject: [PATCH] make the wallpaper stuff a bit more robust and integrated
 around configuration issues

svn path=/trunk/KDE/kdelibs/; revision=948052
---
 containment.cpp |  5 +++++
 wallpaper.cpp   | 25 +++++++++++++++++++++++--
 wallpaper.h     | 35 +++++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/containment.cpp b/containment.cpp
index 5292a7d31..89a16e2f7 100644
--- a/containment.cpp
+++ b/containment.cpp
@@ -1364,6 +1364,11 @@ void Containment::setWallpaper(const QString &pluginName, const QString &mode)
     }
 
     if (newPlugin || newMode) {
+        if (newPlugin && d->wallpaper) {
+            connect(d->wallpaper, SIGNAL(configureRequested()), this, SLOT(configureRequested()));
+            connect(d->wallpaper, SIGNAL(configNeedsSaving()), this, SLOT(configNeedsSaving()));
+        }
+
         emit configNeedsSaving();
     }
 }
diff --git a/wallpaper.cpp b/wallpaper.cpp
index 339a86015..e6aec619e 100644
--- a/wallpaper.cpp
+++ b/wallpaper.cpp
@@ -36,7 +36,8 @@ public:
     WallpaperPrivate(KService::Ptr service, Wallpaper *wallpaper) :
         q(wallpaper),
         wallpaperDescription(service),
-        initialized(false)
+        initialized(false),
+        needsConfig(false)
     {
     };
 
@@ -48,7 +49,8 @@ public:
     KPluginInfo wallpaperDescription;
     QRectF boundingRect;
     KServiceAction mode;
-    bool initialized;
+    bool initialized : 1;
+    bool needsConfig : 1;
 };
 
 Wallpaper::Wallpaper(QObject *parentObject, const QVariantList &args)
@@ -245,6 +247,25 @@ DataEngine *Wallpaper::dataEngine(const QString &name) const
     return d->dataEngine(name);
 }
 
+bool Wallpaper::configurationRequired() const
+{
+    return d->needsConfig;
+}
+
+void Wallpaper::setConfigurationRequired(bool needsConfig, const QString &reason)
+{
+    //TODO: implement something for reason. first, we need to decide where/how
+    //      to communicate it to the user
+    Q_UNUSED(reason)
+
+    if (d->needsConfig == needsConfig) {
+        return;
+    }
+
+    d->needsConfig = needsConfig;
+    emit configurationRequired(needsConfig);
+}
+
 } // Plasma namespace
 
 #include "wallpaper.moc"
diff --git a/wallpaper.h b/wallpaper.h
index 3bf53a4a5..6de9f1ac3 100644
--- a/wallpaper.h
+++ b/wallpaper.h
@@ -227,12 +227,35 @@ class PLASMA_EXPORT Wallpaper : public QObject
          */
         Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
 
+        /**
+         * @return true if the wallpaper currently needs to be configured,
+         *         otherwise, false
+         */
+        bool configurationRequired() const;
+
     Q_SIGNALS:
         /**
          * This signal indicates that wallpaper needs to be repainted.
          */
         void update(const QRectF &exposedArea);
 
+        /**
+         * Emitted when the user wants to configure/change the wallpaper.
+         */
+        void configureRequested();
+
+        /**
+         * Emitted when the state of the wallpaper requiring configuration
+         * changes.
+         */
+        void configurationRequired(bool needsConfig);
+
+        /**
+         * Emitted when the configuration of the wallpaper needs to be saved
+         * to disk.
+         */
+        void configNeedsSaving();
+
     protected:
         /**
          * This constructor is to be used with the plugin loading systems
@@ -253,6 +276,18 @@ class PLASMA_EXPORT Wallpaper : public QObject
          **/
         virtual void init(const KConfigGroup &config);
 
+        /**
+         * When the wallpaper needs to be configured before being usable, this
+         * method can be called to denote that action is required
+         *
+         * @param needsConfiguring true if the applet needs to be configured,
+         *                         or false if it doesn't
+         * @param reason a translated message for the user explaining that the
+         *               applet needs configuring; this should note what needs
+         *               to be configured
+         */
+        void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
+
     private:
         WallpaperPrivate *const d;
 };