* make connectSource apidox a bit clearer

* add DataContainer* containerForSource() for script engine authors to use

CCMAIL:rich@kde.org

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

dataengine.cpp

@@ -187,6 +187,11 @@ void DataEngine::connectAllSources(QObject* visualization) const
     }
 }
 
+DataContainer* DataEngine::containerForSource(const QString &source)
+{
+    return d->requestSource(source);
+}
+
 DataEngine::Data DataEngine::query(const QString& source) const
 {
     DataContainer* s = d->requestSource(source);

dataengine.h

@@ -80,7 +80,7 @@ class PLASMA_EXPORT DataEngine : public QObject
          * Connects a source to an object for data updates. The object must
          * have a slot with the following signature:
          *
-         * SLOT(updated(QString, Plasma::DataEngine::Data))
+         * updated(QString sourceName, Plasma::DataEngine::Data data)
          *
          * The data is a QHash of QVariants keyed by QString names, allowing
          * one data source to provide sets of related data.
@@ -111,6 +111,18 @@ class PLASMA_EXPORT DataEngine : public QObject
          **/
         Q_INVOKABLE void connectAllSources(QObject* viualization) const;
 
+        /**
+         * Retrevies a pointer to the DataContainer for a given source. This method
+         * should not be used if possible. An exception is for script engines that 
+         * can not provide a QMetaObject as required by connectSource for the initial
+         * call to updated(). Using this method, such engines can provide their own
+         * connectSource API.
+         *
+         * @arg source the name of the source.
+         * @return pointer to a DataContainer, or zero on failure
+         **/
+        Q_INVOKABLE DataContainer* containerForSource(const QString &source);
+
         /**
          * Gets the Data associated with a data source.
          *