- fix the init() method not being called

- improve the API docu to be more obvious

svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=682278

dataengine.cpp

@@ -119,7 +119,7 @@ DataEngine::DataEngine(QObject* parent)
     connect(d->updateTimer, SIGNAL(timeout()), this, SLOT(checkForUpdates()));
     //FIXME: we should delay this call; to when is the question.
     //Update DataEngine::init() api docu when fixed
-    init();
+    QTimer::singleShot(0, this, SLOT(startInit()));
 }
 
 DataEngine::~DataEngine()
@@ -195,8 +195,14 @@ DataEngine::Data DataEngine::query(const QString& source) const
     return s->data();
 }
 
+void DataEngine::startInit()
+{
+    init();
+}
+
 void DataEngine::init()
 {
+    // kDebug() << "DataEngine::init() called " << endl;
     // default implementation does nothing. this is for engines that have to
     // start things in motion external to themselves before they can work
 }

dataengine.h

@@ -174,8 +174,6 @@ class PLASMA_EXPORT DataEngine : public QObject
          * method is called the DataEngine is fully constructed and ready to be
          * used. This method should be reimplemented by DataEngine subclasses
          * which have the need to perform a startup routine.
-         *
-         * NOTE: Due to a bug in the DataEngine base implementation this method is never called.
          **/
         virtual void init();
 
@@ -184,6 +182,11 @@ class PLASMA_EXPORT DataEngine : public QObject
          * consumer, this method is called to give the DataEngine the
          * opportunity to create one.
          *
+         * The name of the data source (e.g. the source parameter passed into
+         * setData) it must be the same as the name passed to sourceRequested
+         * otherwise the requesting visualization may not receive notice of a
+         * data update.
+         *
          * @return true if a DataSource was set up, false otherwise
          */
         virtual bool sourceRequested(const QString &name);
@@ -256,7 +259,8 @@ class PLASMA_EXPORT DataEngine : public QObject
 
     protected Q_SLOTS:
         /**
-         * Call this method when you call setData directly on a DataSource.
+         * Call this method when you call setData directly on a DataSource instead
+         * of using the DataEngine::setData methods.
          * If this method is not called, no updated(..) signals will be emitted!
          */
         void checkForUpdates();
@@ -267,6 +271,11 @@ class PLASMA_EXPORT DataEngine : public QObject
          **/
         void removeSource(const QString& source);
 
+        /**
+         * @internal
+         **/
+        void startInit();
+
     private:
         class Private;
         Private* const d;