dataengines and runners in examples

examples/TODO

@@ -6,3 +6,12 @@ Applets:
 * pairsgame
 * samegame
 
+Dataengines:
+* customDataContainers
+* dataEngineTracker
+* simpleEngine
+* sourcesOnRequest
+
+Kpart: only example still to be ported
+
+KRunner: only example still to be ported

examples/dataengines/CMakeLists.txt

@@ -0,0 +1,4 @@
+add_subdirectory(simpleEngine)
+add_subdirectory(sourcesOnRequest)
+add_subdirectory(customDataContainers)
+

examples/dataengines/customDataContainers/CMakeLists.txt

@@ -0,0 +1,10 @@
+set(customDataContainers_SRCS
+    customDataContainersEngine.cpp
+    httpContainer.cpp
+)
+
+kde4_add_plugin(plasma_dataengine_example_customDataContainers ${customDataContainers_SRCS})
+target_link_libraries(plasma_dataengine_example_customDataContainers ${KDE4_PLASMA_LIBS} ${KDE4_KIO_LIBS})
+
+install(TARGETS plasma_dataengine_example_customDataContainers DESTINATION ${PLUGIN_INSTALL_DIR})
+install(FILES plasma-dataengine-example-customDataContainers.desktop DESTINATION ${SERVICES_INSTALL_DIR} )

examples/dataengines/customDataContainers/customDataContainersEngine.cpp

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "customDataContainersEngine.h"
+
+#include "httpContainer.h"
+
+/*
+ This DataEngine shows how to use a subclass of DataContainer to create and 
+ manage sources. This is particularly useful when managing asynchronous requests,
+ such as sources that reflect network, D-Bus, etc. results.
+*/
+
+DataContainersEngine::DataContainersEngine(QObject *parent, const QVariantList &args)
+    : Plasma::DataEngine(parent, args)
+{
+    // We've passed the constructor's args to our parent class.
+    // We're done for now!
+}
+
+bool DataContainersEngine::sourceRequestEvent(const QString &source)
+{
+    // This engine will fetch webpages over http. First thing we do is check
+    // the source to make sure it is indeed an http URL.
+    KUrl url(source);
+    kDebug() << "goin to fetch" << source << url << url.protocol();
+    if (!url.protocol().startsWith("http", Qt::CaseInsensitive)) {
+        return false;
+    }
+
+    // Create a HttpContainer, which is a subclass of Plasma::DataContainer
+    HttpContainer *container = new HttpContainer(url, this);
+
+    // Set the object name to be the same as the source name; DataEngine
+    // relies on this to identify the container. This could also be done
+    // in HttpContainer's constructor, but for the sake of this example
+    // we're dong it here to show that it must be done *before* the
+    // DataContainer subclass is passed to addSource
+    container->setObjectName(source);
+
+    // Now we tell Plasma::DataEngine about this new container
+    addSource(container);
+
+    // Since we successfully set up the source, return true
+    return true;
+}
+
+bool DataContainersEngine::updateSourceEvent(const QString &source)
+{
+    HttpContainer *container = qobject_cast<HttpContainer *>(containerForSource(source));
+    if (container) {
+        container->fetchUrl();
+    }
+
+    // HttpContainer is asynchronous, so the data hasn't actually been updated yet. So
+    // we return false here to let the DataEngine know that nothing has changed quite yet.
+    return false;
+}
+
+// export the plugin; use the plugin name and the class name
+K_EXPORT_PLASMA_DATAENGINE(org.kde.examples.customDataContainers, DataContainersEngine)
+
+// include the moc file so the build system makes it for us
+#include "customDataContainersEngine.moc"
+

examples/dataengines/customDataContainers/customDataContainersEngine.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef DATACONTAINERSENGINE_H
+#define DATACONTAINERSENGINE_H
+
+#include <Plasma/DataEngine>
+
+class DataContainersEngine : public Plasma::DataEngine
+{
+    Q_OBJECT
+
+public:
+    DataContainersEngine(QObject *parent, const QVariantList &args);
+
+protected:
+    bool sourceRequestEvent(const QString &source);
+    bool updateSourceEvent(const QString &source);
+};
+
+#endif

examples/dataengines/customDataContainers/httpContainer.cpp

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "httpContainer.h"
+
+#include <KIO/Job>
+#include <KIO/TransferJob>
+
+HttpContainer::HttpContainer(const KUrl &url, QObject *parent)
+    : Plasma::DataContainer(parent),
+      m_url(url)
+{
+    // Since we are grabbing data over the network, we request a
+    // backing store. This way, if the network is down or on first start
+    // before we get our first reply back, if this source was previously
+    // available, we'll still have our data. This is a very nice "freebie"
+    // DataContainer gives us.
+    setStorageEnabled(true);
+
+    // Now, start an initial fetch.
+    fetchUrl(false);
+}
+
+void HttpContainer::fetchUrl(bool reload)
+{
+    // Now we go about the business of fetching the URL with KIO
+    m_data.clear();
+
+    KIO::TransferJob *job = KIO::get(m_url, reload ? KIO::Reload : KIO::NoReload, KIO::HideProgressInfo);
+    connect(job, SIGNAL(data(KIO::Job*,QByteArray)),
+            this, SLOT(data(KIO::Job*,QByteArray)));
+    connect(job, SIGNAL(finished(KJob*)), this, SLOT(fetchFinished(KJob*)));
+
+    if (m_job) {
+        m_job.data()->kill();
+    }
+
+    m_job = job;
+}
+
+void HttpContainer::data(KIO::Job *job, const QByteArray &data)
+{
+    if (job == m_job.data()) {
+        // we store the data as it arrives
+        m_data.append(data);
+    }
+}
+
+void HttpContainer::fetchFinished(KJob *job)
+{
+    if (!job->error()) {
+        // We now set the data on the source with the retrieved data and some
+        // additional stats. Note that we don't include the source name, as that
+        // is implied as this object *is* the DataContainer. setData is called
+        // with just key/value pairs.
+        setData("Contents", m_data);
+        setData("Size", job->processedAmount(KJob::Bytes));
+
+        // Since we only create TransferJobs, it's safe to just static_cast here.
+        // In many real-world situations, this isn't the safest thing to do and a
+        // qobject_cast with a test on the result is often safer and cleaner.
+        KIO::TransferJob *tjob = static_cast<KIO::TransferJob *>(job);
+        setData("Error Page", tjob->isErrorPage());
+        setData("Mimetype", tjob->mimetype());
+
+        // Let DataContainer know we have data that needs storing
+        setNeedsToBeStored(true);
+
+        // Notify DataContainer that now is a good time to check to see that
+        // data has been updated. This will cause visualizations to be updated.
+        checkForUpdate();
+
+        // Clean up behind ourselves so there isn't unecessary memory usage
+        m_data.clear();
+    }
+}
+
+#include "httpContainer.moc"
+

examples/dataengines/customDataContainers/httpContainer.h

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef HTTPCONTAINER_H
+#define HTTPCONTAINER_H
+
+#include <Plasma/DataContainer>
+
+namespace KIO
+{
+    class Job;
+};
+
+class HttpContainer : public Plasma::DataContainer
+{
+    Q_OBJECT
+
+public:
+    HttpContainer(const KUrl &url, QObject *parent = 0);
+
+    void fetchUrl(bool reload = true);
+
+private Q_SLOTS:
+    void data(KIO::Job *job, const QByteArray &data);
+    void fetchFinished(KJob *);
+
+private:
+    const KUrl m_url;
+    QWeakPointer<KJob> m_job;
+    QByteArray m_data;
+};
+
+#endif

examples/dataengines/customDataContainers/plasma-dataengine-example-customDataContainers.desktop

@@ -0,0 +1,18 @@
+[Desktop Entry]
+Name=Custom DataContainers
+Comment=A demonstration of how to subclass DataContainer
+Type=Service
+Icon=plasma
+
+X-KDE-ServiceTypes=Plasma/DataEngine
+X-KDE-Library=plasma_dataengine_example_customDataContainers
+
+X-KDE-PluginInfo-Author=Aaron Seigo
+X-KDE-PluginInfo-Email=aseigo@kde.org
+X-KDE-PluginInfo-Name=org.kde.examples.customDataContainers
+X-KDE-PluginInfo-Version=1.0
+X-KDE-PluginInfo-Website=http://plasma.kde.org/
+X-KDE-PluginInfo-Category=Examples
+X-KDE-PluginInfo-Depends=
+X-KDE-PluginInfo-License=BSD
+X-KDE-PluginInfo-EnabledByDefault=true

examples/dataengines/dataEngineTracker/README

@@ -0,0 +1,6 @@
+DataEngineTracker is a simple class that follows all activity in a given Plasma::DataEngine.
+
+Simply add it to your project and then instantiate it with a Plasma::DataEngine* as the first
+parameter. This will let you watch sources as they are added, removed and change state. Very
+handy to see how a Plasma::DataEngine is being used and behaving, and as such useful for both
+DataEngine authors as well as those writing code using DataEngines.

examples/dataengines/dataEngineTracker/dataenginetracker.cpp

@@ -0,0 +1,61 @@
+/*
+ *   Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "dataenginetracker.h"
+
+#include <QTime>
+
+DataEngineTracker::DataEngineTracker(Plasma::DataEngine *engine, QObject *parent)
+    : QObject(parent),
+      m_engine(engine)
+{
+    connect(engine, SIGNAL(sourceAdded(QString)), this, SLOT(sourceAdded(QString)));
+    connect(engine, SIGNAL(sourceRemoved(QString)), this, SLOT(sourceRemoved(QString)));
+    engine->connectAllSources(this);
+}
+
+void DataEngineTracker::dataUpdated(const QString &source, const Plasma::DataEngine::Data &data)
+{
+    kDebug() << QTime::currentTime() << source;
+    QHashIterator<QString, QVariant> it(data);
+    while (it.hasNext()) {
+        it.next();
+        kDebug() << "     " << it.key() << it.value();
+    }
+}
+
+void DataEngineTracker::sourceAdded(const QString &source)
+{
+    kDebug() << QTime::currentTime() << source;
+    m_engine->connectSource(source, this);
+}
+
+void DataEngineTracker::sourceRemoved(const QString &source)
+{
+    kDebug() << QTime::currentTime() << source;
+}
+
+#include <dataenginetracker.moc>
+

examples/dataengines/dataEngineTracker/dataenginetracker.h

@@ -0,0 +1,50 @@
+/*
+ *   Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef DATAENGINETRACKER_H
+#define DATAENGINETRACKER_H
+
+#include <QObject>
+
+#include <Plasma/DataEngine>
+
+class DataEngineTracker : QObject
+{
+    Q_OBJECT
+
+public:
+    DataEngineTracker(Plasma::DataEngine *engine, QObject *parent = 0);
+
+public Q_SLOTS:
+    void dataUpdated(const QString &source, const Plasma::DataEngine::Data &data);
+    void sourceAdded(const QString &source);
+    void sourceRemoved(const QString &source);
+
+private:
+    Plasma::DataEngine *m_engine;
+};
+
+#endif
+

examples/dataengines/simpleEngine/CMakeLists.txt

@@ -0,0 +1,9 @@
+set(simpleEngine_SRCS
+    simpleEngine.cpp
+)
+
+kde4_add_plugin(plasma_dataengine_example_simpleEngine ${simpleEngine_SRCS})
+target_link_libraries(plasma_dataengine_example_simpleEngine ${KDE4_PLASMA_LIBS})
+
+install(TARGETS plasma_dataengine_example_simpleEngine DESTINATION ${PLUGIN_INSTALL_DIR})
+install(FILES plasma-dataengine-example-simpleEngine.desktop DESTINATION ${SERVICES_INSTALL_DIR} )

examples/dataengines/simpleEngine/plasma-dataengine-example-simpleEngine.desktop

@@ -0,0 +1,18 @@
+[Desktop Entry]
+Name=Simple DataEngine Example
+Comment=A very basic DataEngine implementation
+Type=Service
+Icon=plasma
+
+X-KDE-ServiceTypes=Plasma/DataEngine
+X-KDE-Library=plasma_dataengine_example_simpleEngine
+
+X-KDE-PluginInfo-Author=Aaron Seigo
+X-KDE-PluginInfo-Email=aseigo@kde.org
+X-KDE-PluginInfo-Name=org.kde.examples.simpleEngine
+X-KDE-PluginInfo-Version=1.0
+X-KDE-PluginInfo-Website=http://plasma.kde.org/
+X-KDE-PluginInfo-Category=Examples
+X-KDE-PluginInfo-Depends=
+X-KDE-PluginInfo-License=BSD
+X-KDE-PluginInfo-EnabledByDefault=true

examples/dataengines/simpleEngine/simpleEngine.cpp

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include <QColor>
+#include <QTime>
+
+#include "simpleEngine.h"
+
+/*
+ This DataEngine provides a static set of data that is created on
+ engine creation. This is a common pattern for DataEngines that relay
+ information such as hardware events and shows the most basic form of
+ a DataEngine
+*/
+
+SimpleEngine::SimpleEngine(QObject *parent, const QVariantList &args)
+    : Plasma::DataEngine(parent, args)
+{
+    // we've passed the constructor's args to our parent class
+    // we're done for now!
+}
+
+void SimpleEngine::init()
+{
+    // init() is called after construction but before anything actually
+    // gets to use the Engine; it's a nice plce for delayed initialization.
+
+    // So now we will set up some sources.
+    // Each DataEngine will, generally, be loaded once. Each DataEngine
+    // can provide multiple sets of data keyed by a string, called "Sources".
+    // In this simplest of cases, we just create some sources arbitrarily.
+
+    // This is the simplest form, with  source name and one bit of data.
+    // Note how the source name is not translated! They can be marked with
+    // I18N_NOOP, however, if they should be translatable in a visualization.
+    setData("Simple Source", i18n("Very simple data"));
+
+    // a source can have multiple entries, differentiated by key names,
+    // which are also not translated:
+    setData("Multiple Source", "First", i18n("First"));
+    setData("Multiple Source", "Second", i18n("Second"));
+
+    // We can also set the data up first and apply it all at once
+    // Note how data types other than strings can be used as well; anything
+    // that works with QVariant, in fact.
+    Plasma::DataEngine::Data data;
+    data.insert("Cow", "mooo");
+    data.insert("Black", QColor(0, 0, 0));
+    data.insert("Time", QTime::currentTime());
+    setData("Another Source", data);
+}
+
+// export the plugin; use the plugin name and the class name
+K_EXPORT_PLASMA_DATAENGINE(org.kde.examples.simpleEngine, SimpleEngine)
+
+// include the moc file so the build system makes it for us
+#include "simpleEngine.moc"
+

examples/dataengines/simpleEngine/simpleEngine.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef SIMPLEENGINE_H
+#define SIMPLEENGINE_H
+
+#include <Plasma/DataEngine>
+
+class SimpleEngine : public Plasma::DataEngine
+{
+    Q_OBJECT
+
+public:
+    SimpleEngine(QObject *parent, const QVariantList &args);
+
+    void init();
+};
+
+#endif

examples/dataengines/sourcesOnRequest/CMakeLists.txt

@@ -0,0 +1,9 @@
+set(sourcesOnRequest_SRCS
+    sourcesOnRequest.cpp
+)
+
+kde4_add_plugin(plasma_dataengine_example_sourcesOnRequest ${sourcesOnRequest_SRCS})
+target_link_libraries(plasma_dataengine_example_sourcesOnRequest ${KDE4_PLASMA_LIBS})
+
+install(TARGETS plasma_dataengine_example_sourcesOnRequest DESTINATION ${PLUGIN_INSTALL_DIR})
+install(FILES plasma-dataengine-example-sourcesOnRequest.desktop DESTINATION ${SERVICES_INSTALL_DIR} )

examples/dataengines/sourcesOnRequest/plasma-dataengine-example-sourcesOnRequest.desktop

@@ -0,0 +1,18 @@
+[Desktop Entry]
+Name=Sources On Request
+Comment=A DataEngine example showing how to respond to requests for source creation and updates
+Type=Service
+Icon=plasma
+
+X-KDE-ServiceTypes=Plasma/DataEngine
+X-KDE-Library=plasma_dataengine_example_sourcesOnRequest
+
+X-KDE-PluginInfo-Author=Aaron Seigo
+X-KDE-PluginInfo-Email=aseigo@kde.org
+X-KDE-PluginInfo-Name=org.kde.examples.sourcesOnRequest
+X-KDE-PluginInfo-Version=1.0
+X-KDE-PluginInfo-Website=http://plasma.kde.org/
+X-KDE-PluginInfo-Category=Examples
+X-KDE-PluginInfo-Depends=
+X-KDE-PluginInfo-License=BSD
+X-KDE-PluginInfo-EnabledByDefault=true

examples/dataengines/sourcesOnRequest/sourcesOnRequest.cpp

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "sourcesOnRequest.h"
+
+#include <Plasma/DataContainer>
+
+/*
+ This DataEngine shows how to created sources on demand as they are requested
+ and update them on visualization-requested update intervals.
+*/
+
+SourcesOnRequestEngine::SourcesOnRequestEngine(QObject *parent, const QVariantList &args)
+    : Plasma::DataEngine(parent, args)
+{
+    // We've passed the constructor's args to our parent class.
+    // We're done for now!
+}
+
+bool SourcesOnRequestEngine::sourceRequestEvent(const QString &source)
+{
+    // When this method is called we can assume that:
+    //   * the source does not exist yet
+    //   * the source name parameter passed in is not an empty string
+    //   * we are free to reject creating the source if we wish
+
+    // We're going to reject any sources that start with the letter 'a'
+    // to demonstrate how to reject a request in a DataEngine.
+    if (source.startsWith('a') || source.startsWith('A')) {
+        return false;
+    }
+
+    // For every other source, we're going to start an update count for it.
+    // Critically, we create a source before returning that has the exact
+    // same key as the source string. We MUST NOT create a source of a different
+    // name as that will cause unexpected results for the visualization.
+    // In such a case the DataEngine will remain happy and Do The Right Thing(tm)
+    // but the visualization will not get the source connected to it as it
+    // expects. So ALWAYS key the new data by the source string as below:
+    setData(source, "Update Count", 0);
+
+    // as we successfully set up the source, return true
+    return true;
+}
+
+bool SourcesOnRequestEngine::updateSourceEvent(const QString &source)
+{
+    // Whenever a visualization has requested an update, such as when passing
+    // an update interval to DataEngine::connectSource, this method will be called.
+    // When this method is called we can assume that:
+    //     * the source exists
+    //     * it hasn't been updated more frequently than the minimum update interval
+    //
+    // If not data is set in this method, then the update is skipped for the visualiation
+    // and that is just fine.
+    //
+    // We can also set data for other sources here if we wish, but as with
+    // sourceRequestEvent this may not be what the visualization expects. Unlike in
+    // sourceRequestEvent, however, this will result in expected behavior: visualizations
+    // connected to the sources which have setData called for them will be notified
+    // of these changes.
+    setData(source, "Update Count", containerForSource(source)->data().value("Update Count").toInt() + 1);
+
+    // Since we updated the source immediately here, we need to return true so the DataEngine
+    // knows to continue with the update notification for visualizations.
+    return true;
+}
+
+// export the plugin; use the plugin name and the class name
+K_EXPORT_PLASMA_DATAENGINE(org.kde.examples.sourcesOnRequest, SourcesOnRequestEngine)
+
+// include the moc file so the build system makes it for us
+#include "sourcesOnRequest.moc"
+

examples/dataengines/sourcesOnRequest/sourcesOnRequest.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2011 Aaron Seigo <aseigo@kde.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ *    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ *    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ *    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ *    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ *    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ *    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ *    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef SOURCESONREQUESTENGINE_H
+#define SOURCESONREQUESTENGINE_H
+
+#include <Plasma/DataEngine>
+
+class SourcesOnRequestEngine : public Plasma::DataEngine
+{
+    Q_OBJECT
+
+public:
+    SourcesOnRequestEngine(QObject *parent, const QVariantList &args);
+
+protected:
+    bool sourceRequestEvent(const QString &source);
+    bool updateSourceEvent(const QString &source);
+};
+
+#endif

examples/kpart/CMakeLists.txt

@@ -0,0 +1,17 @@
+set(plasma_example_kpart_shell_SRCS
+   main.cpp
+   containmentshell.cpp
+   testshellpluginloader.cpp
+   appletselector.cpp
+)
+
+kde4_add_ui_files(plasma_example_kpart_shell_SRCS appletselector.ui)
+kde4_add_executable(plasma-example-kpart-shell ${plasma_example_kpart_shell_SRCS})
+
+target_link_libraries(plasma-example-kpart-shell ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} ${KDE4_PLASMA_LIBS} )
+
+########### install files ###############
+install(TARGETS plasma-example-kpart-shell ${INSTALL_TARGETS_DEFAULT_ARGS} )
+install( PROGRAMS plasma-example-kpart-shell.desktop  DESTINATION  ${XDG_APPS_INSTALL_DIR} )
+install(FILES plasma-default-layoutrc DESTINATION ${DATA_INSTALL_DIR}/plasma-example-kpart-shell/)
+install( FILES plasma-kpart-shellui.rc  DESTINATION ${DATA_INSTALL_DIR}/plasma-example-kpart-shell/ )

examples/kpart/appletselector.cpp

@@ -0,0 +1,67 @@
+/* 
+ * Copyright 2010 Aleix Pol Gonzalez <aleixpol@kde.org>
+ *
+ * This library 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 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public License
+ * along with this library; see the file COPYING.LIB.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include "appletselector.h"
+#include "ui_appletselector.h"
+
+#include <plasma/applet.h>
+#include <QStandardItemModel>
+
+AppletSelector::AppletSelector(QObject* parent, const QVariantList& args)
+    : KDialog()
+{
+    Q_UNUSED(args);
+
+    setButtons(Close);
+    QWidget* w = new QWidget(this);
+
+    m_ui = new Ui::AppletSelector;
+    m_ui->setupUi(w);
+
+    m_ui->plugins->header()->setSortIndicator(0, Qt::AscendingOrder);
+
+    setMainWidget(w);
+
+    QStandardItemModel* model = new QStandardItemModel(this);
+    const KPluginInfo::List list= Plasma::Applet::listAppletInfo();
+    foreach(const KPluginInfo& info, list) {
+        QStandardItem* item = new QStandardItem(KIcon(info.icon()), info.name());
+        item->setEditable(false);
+        item->setToolTip(info.comment());
+        item->setData(info.pluginName(), Qt::UserRole+1);
+
+        model->appendRow(item);
+    }
+
+    m_ui->plugins->setModel(model);
+
+    connect(m_ui->plugins, SIGNAL(doubleClicked(QModelIndex)), SLOT(selected(QModelIndex)));
+}
+
+AppletSelector::~AppletSelector()
+{
+    delete m_ui;
+}
+
+void AppletSelector::selected(const QModelIndex& idx)
+{
+    emit addApplet(idx.data(Qt::UserRole+1).toString());
+}
+
+#include "appletselector.moc"

examples/kpart/appletselector.h

@@ -0,0 +1,44 @@
+/* This file is part of KDevelop
+  Copyright 2010 Aleix Pol Gonzalez <aleixpol@kde.org>
+
+  This library 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 of the License, or (at your option) any later version.
+
+  This library 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
+  Library General Public License for more details.
+
+  You should have received a copy of the GNU Library General Public License
+  along with this library; see the file COPYING.LIB.  If not, write to
+  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+  Boston, MA 02110-1301, USA.
+*/
+
+#ifndef APPLETSELECTOR_H
+#define APPLETSELECTOR_H
+
+#include <KDE/KDialog>
+
+class QModelIndex;
+namespace Ui { class AppletSelector; }
+
+class AppletSelector : public KDialog
+{
+Q_OBJECT
+public:
+    explicit AppletSelector(QObject* parent = 0, const QVariantList& args = QVariantList());
+    ~AppletSelector();
+public slots:
+    void selected(const QModelIndex& idx);
+
+signals:
+    void addApplet(const QString& name);
+
+private:
+    Ui::AppletSelector* m_ui;
+};
+
+#endif // APPLETSELECTOR_H

examples/kpart/appletselector.ui

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>AppletSelector</class>
+ <widget class="QWidget" name="AppletSelector">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>400</width>
+    <height>300</height>
+   </rect>
+  </property>
+  <layout class="QVBoxLayout" name="verticalLayout">
+   <item>
+    <widget class="QLabel" name="label">
+     <property name="text">
+      <string>Double-click on the widget you want to add:</string>
+     </property>
+    </widget>
+   </item>
+   <item>
+    <widget class="QTreeView" name="plugins">
+     <property name="rootIsDecorated">
+      <bool>false</bool>
+     </property>
+     <property name="itemsExpandable">
+      <bool>false</bool>
+     </property>
+     <property name="sortingEnabled">
+      <bool>true</bool>
+     </property>
+     <attribute name="headerVisible">
+      <bool>false</bool>
+     </attribute>
+     <attribute name="headerVisible">
+      <bool>false</bool>
+     </attribute>
+    </widget>
+   </item>
+  </layout>
+ </widget>
+ <resources/>
+ <connections/>
+</ui>

examples/kpart/containmentshell.cpp

@@ -0,0 +1,95 @@
+/*
+*   Copyright 2010 Ryan Rix <ry@n.rix.si>
+*   Copyright 2010 Siddharth Sharma <siddharth.kde@gmail.com>
+*
+*   This program is free software; you can redistribute it and/or modify
+*   it under the terms of the GNU Library General Public License version 2 as
+*   published by the Free Software Foundation
+*
+*   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.
+*/
+
+#include "containmentshell.h"
+#include "testshellpluginloader.h"
+#include "appletselector.h"
+
+#include <KService>
+#include <KMessageBox>
+#include <KDebug>
+#include <KStandardAction>
+#include <KActionCollection>
+
+
+#include <Plasma/Containment>
+
+#include <QApplication>
+
+ContainmentShell::ContainmentShell()
+    : KParts::MainWindow( ),
+      m_dialog(0)
+{
+    setXMLFile("plasma-kpart-shellui.rc");
+
+    KAction *action = KStandardAction::quit(qApp, SLOT(quit()), actionCollection());
+    action = new KAction("&Configure", actionCollection());
+    connect(action, SIGNAL(triggered()), this, SLOT(optionsPreferences()));
+    actionCollection()->addAction("options_configure", action);
+
+    // this routine will find and load our Part.  it finds the Part by
+    // name which is a bad idea usually.. but it's alright in this
+    // case since our Part is made for this Shell
+    KService::Ptr service = KService::serviceByDesktopPath( "plasma-kpart.desktop" );
+
+    if (service) {
+        Plasma::PluginLoader *loader = new TestShellPluginLoader();
+        m_part = service->createInstance<KParts::ReadOnlyPart>(0, QVariantList() << qVariantFromValue(loader));
+
+        if (m_part) {
+            // tell the KParts::MainWindow that this is indeed the main widget
+            setCentralWidget(m_part->widget());
+
+            // and integrate the part's GUI with the shell's
+            createGUI(m_part);
+        } else {
+            // For whatever reason the part didn't load
+            KMessageBox::error(this, "Could not instantiate our Part!");
+            qApp->quit();
+        }
+    } else {
+        // if we couldn't find our Part, we exit since the Shell by
+        // itself can't do anything useful
+        KMessageBox::error(this, "Could not find our Part!");
+        qApp->quit();
+        // we return here, cause qApp->quit() only means "exit the
+        // next time we enter the event loop...
+        return;
+    }
+
+    // apply the saved mainwindow settings, if any, and ask the mainwindow
+    // to automatically save settings if changed: window size, toolbar
+    // position, icon size, etc.
+    setAutoSaveSettings();
+}
+
+ContainmentShell::~ContainmentShell()
+{
+}
+
+void ContainmentShell::optionsPreferences()
+{
+    if (!m_dialog) {
+        m_dialog = new AppletSelector( m_part );
+        connect( m_dialog, SIGNAL(addApplet(QString)), m_part, SLOT(addApplet(QString)) );
+    }
+    m_dialog->show();
+}
+
+#include "containmentshell.moc"

examples/kpart/containmentshell.h

@@ -0,0 +1,49 @@
+/*
+*   Copyright 2010 Ryan Rix <ry@n.rix.si>
+*   Copyright 2010 Siddharth Sharma <siddharth.kde@gmail.com>
+*
+*   This program is free software; you can redistribute it and/or modify
+*   it under the terms of the GNU Library General Public License version 2 as
+*   published by the Free Software Foundation
+*
+*   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 CONTAINMENTSHELL_H
+#define CONTAINMENTSHELL_H
+
+#include <kparts/mainwindow.h>
+#include <KDialog>
+
+/**
+ * This is the application "Shell".  It has a menubar, toolbar, and
+ * statusbar but relies on the "Part" to do all the real work.
+ *
+ * @short Generic Application Shell
+ * @author Ryan Rix <ry@n.rix.si>
+ * @version 0.01
+ */
+class ContainmentShell : public KParts::MainWindow
+{
+Q_OBJECT
+public:
+    ContainmentShell();
+    virtual ~ContainmentShell();
+
+public Q_SLOTS:
+    void optionsPreferences();
+
+private:
+    KParts::Part* m_part;
+    KDialog* m_dialog;
+};
+
+#endif // CONTAINMENTSHELL_H

examples/kpart/main.cpp

@@ -0,0 +1,43 @@
+/*
+*   Copyright 2010 Ryan Rix <ry@n.rix.si>
+*
+*   This program is free software; you can redistribute it and/or modify
+*   it under the terms of the GNU Library General Public License version 2 as
+*   published by the Free Software Foundation
+*
+*   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.
+*/
+
+#include "containmentshell.h"
+#include <KApplication>
+#include <KAboutData>
+#include <KCmdLineArgs>
+
+static const char version[] = "0.1";
+
+int main(int argc, char** argv)
+{
+    KAboutData about("plasma-kpart-shell", 0, ki18n("Plasma KPart Shell"), version, ki18n("A KDE KPart Application"), KAboutData::License_GPL, ki18n("(C) 2010 Ryan Rix"), KLocalizedString(), 0, "ry@n.rix.si");
+    about.addAuthor( ki18n("Ryan Rix"), KLocalizedString(), "ry@n.rix.si" );
+    KCmdLineArgs::init(argc, argv, &about);
+
+    KApplication app;
+
+    // see if we are starting with session management
+    if (app.isSessionRestored()) {
+        RESTORE(ContainmentShell)
+    } else {
+        ContainmentShell *widget = new ContainmentShell;
+        widget->show();
+    }
+
+    return app.exec();
+}

examples/kpart/plasma-default-layoutrc

@@ -0,0 +1,61 @@
+[Containments][1]
+activity=Newspaper
+desktop=-1
+formfactor=0
+geometry=806,0,800,480
+immutability=1
+location=0
+plugin=newspaper
+screen=0
+wallpaperplugin=image
+wallpaperpluginmode=SingleImage
+zvalue=0
+
+[Containments][1][ToolBox]
+corner=7
+offset=0
+
+[Containments][1][Applets][1]
+geometry=14,38,343,236
+immutability=1
+plugin=news
+zvalue=52
+
+[Containments][1][Applets][1][LayoutInformation]
+Column=0
+Order=0
+
+
+[Containments][1][Applets][2]
+geometry=14,278,343,188
+immutability=1
+plugin=weather
+zvalue=57
+
+[Containments][1][Applets][2][LayoutInformation]
+Column=0
+Order=1
+
+[Containments][1][Applets][3]
+geometry=1000,38,424,241
+immutability=1
+plugin=opendesktop
+zvalue=47
+
+[Containments][1][Applets][3][LayoutInformation]
+Column=1
+Order=0
+
+[Containments][1][Applets][4]
+geometry=1000,283,424,182
+immutability=1
+plugin=knowledgebase
+zvalue=47
+
+[Containments][1][Applets][4][LayoutInformation]
+Column=1
+Order=1
+
+
+[General]
+immutability=1

examples/kpart/plasma-example-kpart-shell.desktop

@@ -0,0 +1,24 @@
+[Desktop Entry]
+Name=plasma-kpart-shell
+Name[en_GB]=plasma-kpart-shell
+Name[ia]=plasma-kpart-shell
+Name[nl]=plasma-kpart-shell
+Name[pt]=plasma-kpart-shell
+Name[pt_BR]=plasma-kpart-shell
+Name[sv]=Plasma-delprogramskal
+Name[uk]=plasma-kpart-shell
+Name[x-test]=xxplasma-kpart-shellxx
+Exec=plasma-example-kpart-shell %i -caption "%c"
+Icon=plasma-example-kpart-shell
+Type=Application
+X-DocPath=plasma-kpart-shell/index.html
+GenericName=A KPart shell for Plasma
+GenericName[en_GB]=A KPart shell for Plasma
+GenericName[ia]=Un shell de KPart pro Plasma
+GenericName[nl]=Een KPart-shell voor Plasma
+GenericName[pt]=Uma consola de KParts para o Plasma
+GenericName[pt_BR]=Uma shell de KPart para o Plasma
+GenericName[sv]=Ett delprogramskal för Plasma
+GenericName[uk]=Оболонка модулів для Плазми
+GenericName[x-test]=xxA KPart shell for Plasmaxx
+Terminal=false

examples/kpart/plasma-kpart-shellui.rc

@@ -0,0 +1,31 @@
+<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
+<kpartgui name="plasma-kpart-shell" version="2">
+<MenuBar>
+  <Menu noMerge="1" name="file"><text>&amp;File</text>
+    <Action name="file_new"/>
+    <Action name="file_open"/>
+    <Separator/>
+    <Merge/>
+    <Separator/>
+    <Action name="file_quit"/>
+  </Menu>
+  <Menu noMerge="1" name="settings"><text>&amp;Settings</text>
+    <Action name="options_show_toolbar"/>
+    <Action name="options_show_statusbar"/>
+    <Merge name="show_merge"/>
+    <Separator/>
+    <Action name="options_configure_keybinding"/>
+    <Action name="options_configure_toolbars"/>
+    <Action name="options_configure"/>
+    <Merge name="configure_merge"/>
+    <Separator/>
+    <Merge/>
+  </Menu>
+</MenuBar>
+<ToolBar noMerge="1" name="mainToolBar"><text>Main Toolbar</text>
+  <Action name="file_new"/>
+  <Merge/>
+  <Action name="help"/>
+</ToolBar>
+</kpartgui>
+

examples/kpart/testshellpluginloader.cpp

@@ -0,0 +1,49 @@
+/*
+*   Copyright 2010 Ryan Rix <ry@n.rix.si>
+*
+*   This program is free software; you can redistribute it and/or modify
+*   it under the terms of the GNU Library General Public License version 2 as
+*   published by the Free Software Foundation
+*
+*   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.
+*/
+
+#include "testshellpluginloader.h"
+
+#include <KDebug>
+
+#include <Plasma/Plasma>
+#include <Plasma/Applet>
+#include <Plasma/Service>
+#include <Plasma/DataEngine>
+
+TestShellPluginLoader::~TestShellPluginLoader()
+{
+}
+
+Plasma::Applet* TestShellPluginLoader::internalLoadApplet (const QString &name, uint appletId, const QVariantList &args)
+{
+    kDebug() << "loadApplet called with" << name << appletId << args;
+    return 0;
+}
+
+Plasma::DataEngine* TestShellPluginLoader::internalLoadDataEngine(const QString &name)
+{
+    kDebug() << "loadEngine called with" << name;
+    return 0;
+}
+
+Plasma::Service* TestShellPluginLoader::internalLoadService(const QString &name, const QVariantList &args, QObject *parent)
+{
+    kDebug() << "loadService called with" << name << args << parent;
+    return 0;
+}
+

examples/kpart/testshellpluginloader.h

@@ -0,0 +1,35 @@
+/*
+*   Copyright 2010 Ryan Rix <ry@n.rix.si>
+*
+*   This program is free software; you can redistribute it and/or modify
+*   it under the terms of the GNU Library General Public License version 2 as
+*   published by the Free Software Foundation
+*
+*   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 TESTSHELLPLUGINLOADER_H
+#define TESTSHELLPLUGINLOADER_H
+
+#include <plasma/pluginloader.h>
+
+class TestShellPluginLoader : public Plasma::PluginLoader
+{
+public:
+    ~TestShellPluginLoader();
+
+    Plasma::Applet* internalLoadApplet (const QString &name, uint appletId = 0,
+                               const QVariantList &args = QVariantList());
+    Plasma::DataEngine* internalLoadDataEngine(const QString &name);
+    Plasma::Service* internalLoadService(const QString &name, const QVariantList &args, QObject *parent = 0);
+};
+
+#endif

examples/runner/CMakeLists.txt

@@ -0,0 +1,16 @@
+# Project Needs a name, of course
+project(RunnerExample)
+
+add_definitions(${QT_DEFINITIONS} ${KDE4_DEFINITIONS})
+include_directories(${KDE4_INCLUDES})
+
+# We add our source code here
+set(example_SRCS homefilesrunner.cpp)
+
+# Now make sure all files get to the right place
+kde4_add_plugin(plasma_runner_example_homefiles ${example_SRCS})
+target_link_libraries(plasma_runner_example_homefiles ${KDE4_PLASMA_LIBS} ${KDE4_KIO_LIBS})
+
+# Install the library and .desktop file
+install(TARGETS plasma_runner_example_homefiles DESTINATION ${PLUGIN_INSTALL_DIR})
+install(FILES plasma-runner-example-homefiles.desktop DESTINATION ${SERVICES_INSTALL_DIR})

examples/runner/Messages.sh

@@ -0,0 +1,2 @@
+#! /usr/bin/env bash
+$XGETTEXT *.cpp -o $podir/plasma_runner_example_homefiles.pot

examples/runner/homefilesrunner.cpp

@@ -0,0 +1,162 @@
+/*
+Copyright 2009 Aaron Seigo <aseigo@kde.org>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+   IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#include "homefilesrunner.h"
+
+#include <QCheckBox>
+#include <QDir>
+#include <QFileInfo>
+#include <QVBoxLayout>
+
+#include <KDebug>
+#include <KMimeType>
+#include <KRun>
+
+HomeFilesRunner::HomeFilesRunner(QObject *parent, const QVariantList &args)
+    : AbstractRunner(parent, args)
+{
+    setIgnoredTypes(Plasma::RunnerContext::NetworkLocation |
+                    Plasma::RunnerContext::Executable |
+                    Plasma::RunnerContext::ShellCommand);
+    setSpeed(SlowSpeed);
+    setPriority(LowPriority);
+    setHasRunOptions(true);
+}
+
+void HomeFilesRunner::init()
+{
+    reloadConfiguration();
+    connect(this, SIGNAL(prepare()), this, SLOT(prepareForMatchSession()));
+    connect(this, SIGNAL(teardown()), this, SLOT(matchSessionFinished()));
+}
+
+void HomeFilesRunner::reloadConfiguration()
+{
+    KConfigGroup c = config();
+    m_triggerWord = c.readEntry("trigger", QString());
+    if (!m_triggerWord.isEmpty()) {
+        m_triggerWord.append(' ');
+    }
+
+    m_path = c.readPathEntry("path", QDir::homePath());
+    QFileInfo pathInfo(m_path);
+    if (!pathInfo.isDir()) {
+        m_path = QDir::homePath();
+    }
+
+    QList<Plasma::RunnerSyntax> syntaxes;
+    Plasma::RunnerSyntax syntax(QString("%1:q:").arg(m_triggerWord),
+                                i18n("Finds files matching :q: in the %1 folder", m_path));
+    syntaxes.append(syntax);
+    setSyntaxes(syntaxes);
+}
+
+void HomeFilesRunner::prepareForMatchSession()
+{
+
+}
+
+void HomeFilesRunner::match(Plasma::RunnerContext &context)
+{
+    QString query = context.query();
+    if (query == QChar('.') || query == "..") {
+        return;
+    }
+
+    if (!m_triggerWord.isEmpty()) {
+        if (!query.startsWith(m_triggerWord)) {
+            return;
+        }
+
+        query.remove(0, m_triggerWord.length());
+    }
+
+    if (query.length() > 2) {
+        query.prepend('*').append('*');
+    }
+
+    QDir dir(m_path);
+    QList<Plasma::QueryMatch> matches;
+
+    foreach (const QString &file, dir.entryList(QStringList(query))) {
+        const QString path = dir.absoluteFilePath(file);
+        if (!path.startsWith(m_path)) {
+            // this file isn't in our directory; looks like we got a query with some
+            // ..'s in it!
+            continue;
+        }
+
+        if (!context.isValid()) {
+            return;
+        }
+
+        Plasma::QueryMatch match(this);
+        match.setText(i18n("Open %1", path));
+        match.setData(path);
+        match.setId(path);
+        if (m_iconCache.contains(path)) {
+            match.setIcon(m_iconCache.value(path));
+        } else {
+            KIcon icon(KMimeType::iconNameForUrl(path));
+            m_iconCache.insert(path, icon);
+            match.setIcon(icon);
+        }
+
+        if (file.compare(query, Qt::CaseInsensitive)) {
+            match.setRelevance(1.0);
+            match.setType(Plasma::QueryMatch::ExactMatch);
+        } else {
+            match.setRelevance(0.8);
+        }
+
+        matches.append(match);
+    }
+
+    context.addMatches(context.query(), matches);
+}
+
+void HomeFilesRunner::matchSessionFinished()
+{
+    m_iconCache.clear();
+}
+
+void HomeFilesRunner::run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
+{
+    Q_UNUSED(context)
+    // KRun autodeletes itself, so we can just create it and forget it!
+    KRun *opener = new KRun(match.data().toString(), 0);
+    opener->setRunExecutables(false);
+}
+
+void HomeFilesRunner::createRunOptions(QWidget *widget)
+{
+    QVBoxLayout *layout = new QVBoxLayout(widget);
+    QCheckBox *cb = new QCheckBox(widget);
+    cb->setText(i18n("This is just for show"));
+    layout->addWidget(cb);
+}
+
+K_EXPORT_PLASMA_RUNNER(example-homefiles, HomeFilesRunner)
+

examples/runner/homefilesrunner.h

@@ -0,0 +1,59 @@
+/*
+Copyright 2009 Aaron Seigo <aseigo@kde.org>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+   IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#ifndef HOMEFILES_H
+#define HOMEFILES_H
+
+#include <Plasma/AbstractRunner>
+
+#include <QHash>
+
+#include <KIcon>
+
+class HomeFilesRunner : public Plasma::AbstractRunner
+{
+    Q_OBJECT
+
+public:
+    HomeFilesRunner(QObject *parent, const QVariantList &args);
+
+    void match(Plasma::RunnerContext &context);
+    void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match);
+    void createRunOptions(QWidget *widget);
+    void reloadConfiguration();
+
+protected Q_SLOTS:
+    void init();
+    void prepareForMatchSession();
+    void matchSessionFinished();
+
+private:
+    QHash<QString, KIcon> m_iconCache;
+    QString m_path;
+    QString m_triggerWord;
+};
+
+#endif
+

examples/runner/plasma-runner-example-homefiles.desktop

@@ -0,0 +1,17 @@
+[Desktop Entry]
+Name=Home Files
+Comment=Part of a tutorial demonstrating how to create Runner plugins
+Icon=user-home
+Type=Service
+X-KDE-ServiceTypes=Plasma/Runner
+
+X-KDE-Library=plasma_runner_example_homefiles
+X-KDE-PluginInfo-Author=Aaron Seigo
+X-KDE-PluginInfo-Email=aseigo@kde.org
+X-KDE-PluginInfo-Name=example-homefiles
+X-KDE-PluginInfo-Version=0.1
+X-KDE-PluginInfo-Website=http://plasma.kde.org/
+X-KDE-PluginInfo-Category=Examples
+X-KDE-PluginInfo-Depends=
+X-KDE-PluginInfo-License=GPL
+X-KDE-PluginInfo-EnabledByDefault=true