provide a way for runners to define their syntax; may experience some small api shifts yet, but nothing major and it works.

svn path=/trunk/KDE/kdelibs/; revision=944088

CMakeLists.txt

@@ -88,6 +88,7 @@ set(plasma_LIB_SRCS
     querymatch.cpp
     runnercontext.cpp
     runnermanager.cpp
+    runnersyntax.cpp
     scripting/appletscript.cpp
     scripting/dataenginescript.cpp
     scripting/runnerscript.cpp
@@ -216,6 +217,7 @@ set(plasma_LIB_INCLUDES
     querymatch.h
     runnercontext.h
     runnermanager.h
+    runnersyntax.h
     service.h
     servicejob.h
     svg.h

abstractrunner.cpp

@@ -26,6 +26,7 @@
 #include <QTimer>
 
 #include <kdebug.h>
+#include <kicon.h>
 #include <kplugininfo.h>
 #include <kservicetypetrader.h>
 #include <kstandarddirs.h>
@@ -96,6 +97,7 @@ public:
     int fastRuns;
     Package *package;
     QHash<QString, QAction*> actions;
+    QList<RunnerSyntax> syntaxes;
 };
 
 K_GLOBAL_STATIC(QMutex, s_bigLock)
@@ -132,6 +134,21 @@ void AbstractRunner::reloadConfiguration()
 {
 }
 
+void AbstractRunner::addSyntax(const RunnerSyntax &syntax)
+{
+    d->syntaxes.append(syntax);
+}
+
+void AbstractRunner::clearSyntaxes()
+{
+    d->syntaxes.clear();
+}
+
+QList<RunnerSyntax> AbstractRunner::syntaxes() const
+{
+    return d->syntaxes;
+}
+
 void AbstractRunner::performMatch(Plasma::RunnerContext &localContext)
 {
     static const int reasonableRunTime = 1500;
@@ -281,9 +298,19 @@ QString AbstractRunner::name() const
     if (!d->runnerDescription.isValid()) {
         return objectName();
     }
+
     return d->runnerDescription.name();
 }
 
+QIcon AbstractRunner::icon() const
+{
+    if (!d->runnerDescription.isValid()) {
+        return QIcon();
+    }
+
+    return KIcon(d->runnerDescription.icon());
+}
+
 QString AbstractRunner::id() const
 {
     if (!d->runnerDescription.isValid()) {
@@ -297,6 +324,7 @@ QString AbstractRunner::description() const
     if (!d->runnerDescription.isValid()) {
         return objectName();
     }
+
     return d->runnerDescription.property("Comment").toString();
 }
 

abstractrunner.h

@@ -28,8 +28,9 @@
 #include <kservice.h>
 
 #include <plasma/plasma_export.h>
-#include <plasma/runnercontext.h>
 #include <plasma/querymatch.h>
+#include <plasma/runnercontext.h>
+#include <plasma/runnersyntax.h>
 #include <plasma/version.h>
 
 class QAction;
@@ -189,20 +190,25 @@ class PLASMA_EXPORT AbstractRunner : public QObject
         void setIgnoredTypes(RunnerContext::Types types);
 
         /**
-          * Returns the user visible engine name for the Runner
+          * @return the user visible engine name for the Runner
           */
         QString name() const;
 
         /**
-          * Returns an id string for the Runner
+          * @return an id string for the Runner
           */
         QString id() const;
 
         /**
-          * Returns the description of this Runner
+          * @return the description of this Runner
           */
         QString description() const;
 
+        /**
+         * @return the icon for this Runner
+         */
+        QIcon icon() const;
+
         /**
          * Accessor for the associated Package object if any.
          *
@@ -218,6 +224,12 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          */
         virtual void reloadConfiguration();
 
+        /**
+         * @return the syntaxes the runner has registered that it accepts and understands
+         * @since 4.3
+         */
+        QList<RunnerSyntax> syntaxes() const;
+
         /**
          * Access to a shared lock that all runners (and code that manages/interacts with them)
          * can share to protect access to non-thread-safe shared code or data.
@@ -333,12 +345,29 @@ class PLASMA_EXPORT AbstractRunner : public QObject
          * Returns all registered actions
          */
         QHash<QString, QAction*> actions() const;
+
         /**
          * Clears the action registry.
          * The action pool deletes the actions.
          */
         void clearActions();
 
+        /**
+         * Adds a registed syntax that this runner understands. This is used to
+         * display to the user what this runner can understand and how it can be
+         * used.
+         *
+         * @arg syntax the syntax to register
+         * @since 4.3
+         */
+        void addSyntax(const RunnerSyntax &syntax);
+
+        /**
+         * Clears all registered syntaxes.
+         * @since 4.3
+         */
+        void clearSyntaxes();
+
     protected Q_SLOTS:
         void init();
 

runnermanager.cpp

@@ -142,7 +142,14 @@ public:
                     }
 
                     if (runner) {
-                        kDebug() << "loading runner:" << service->name();
+                        kDebug() << "================= loading runner:" << service->name() << "=================";
+
+                        /*
+                        foreach (const RunnerSyntax &syntax, runner->syntaxes()) {
+                            kDebug() << syntax.exampleQueriesWithTermDescription().join(", ") << " ==> " << syntax.description();
+                        }
+                        */
+
                         runners.insert(runnerName, runner);
                     } else {
                         kDebug() << "failed to load runner:" << service->name()
@@ -259,6 +266,11 @@ AbstractRunner* RunnerManager::runner(const QString &name) const
     return d->runners.value(name, 0);
 }
 
+QList<AbstractRunner *> RunnerManager::runners() const
+{
+    return d->runners.values();
+}
+
 RunnerContext* RunnerManager::searchContext() const
 {
     return &d->context;

runnermanager.h

@@ -60,6 +60,11 @@ class PLASMA_EXPORT RunnerManager : public QObject
          */
         AbstractRunner *runner(const QString &name) const;
 
+        /**
+         * @return the list of all currently loaded runners
+         */
+        QList<AbstractRunner *> runners() const;
+
         /**
          * Retrieves the current context
          * @return pointer to the current context

runnersyntax.cpp

@@ -0,0 +1,105 @@
+/*
+ *   Copyright 2009 Aaron Seigo <aseigo@kde.org>
+ *
+ *   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.
+ */
+
+#include "runnersyntax.h"
+
+#include <klocalizedstring.h>
+
+namespace Plasma
+{
+
+class RunnerSyntaxPrivate
+{
+public:
+    RunnerSyntaxPrivate(const QString &s, const QString &d)
+        : description(d)
+    {
+        exampleQueries.append(s);
+    }
+
+    QStringList exampleQueries;
+    QString description;
+    QString termDescription;
+};
+
+RunnerSyntax::RunnerSyntax(const QString &exampleQuery, const QString &description)
+    : d(new RunnerSyntaxPrivate(exampleQuery, description))
+{
+}
+
+RunnerSyntax::RunnerSyntax(const RunnerSyntax &other)
+    : d(new RunnerSyntaxPrivate(*other.d))
+{
+}
+
+RunnerSyntax &RunnerSyntax::operator=(const RunnerSyntax &rhs)
+{
+    *d = *rhs.d;
+    return *this;
+}
+
+void RunnerSyntax::addExampleQuery(const QString &exampleQuery)
+{
+    d->exampleQueries.append(exampleQuery);
+}
+
+QStringList RunnerSyntax::exampleQueries() const
+{
+    return d->exampleQueries;
+}
+
+QStringList RunnerSyntax::exampleQueriesWithTermDescription() const
+{
+    QStringList queries;
+    const QString termDesc("<" + searchTermDescription() + ">");
+    foreach (QString query, d->exampleQueries) {
+        queries << query.replace(":q:", termDesc);
+    }
+
+    return queries;
+}
+
+void RunnerSyntax::setDescription(const QString &description)
+{
+    d->description = description;
+}
+
+QString RunnerSyntax::description() const
+{
+    QString description = d->description;
+    description.replace(":q:", "<" + searchTermDescription() + ">");
+    return description;
+}
+
+void RunnerSyntax::setSearchTermDescription(const QString &description)
+{
+    d->termDescription = description;
+}
+
+QString RunnerSyntax::searchTermDescription() const
+{
+    if (d->termDescription.isEmpty()) {
+        return i18n("search term");
+    }
+
+    return d->termDescription;
+}
+
+} // Plasma namespace
+

runnersyntax.h

@@ -0,0 +1,124 @@
+/*
+ *   Copyright 2009 Aaron Seigo <aseigo@kde.org>
+ *
+ *   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_RUNNERSYNTAX_H
+#define PLASMA_RUNNERSYNTAX_H
+
+#include <QString>
+#include <QStringList>
+
+#include <plasma/plasma.h>
+
+namespace Plasma
+{
+
+class RunnerSyntaxPrivate;
+/**
+ * @class RunnerSyntax
+ * @since 4.3
+ *
+ * Represents a query prototype that the runner accepts. These can be
+ * created and registered with AbstractRunner::addSyntax(Syntax &) to
+ * allow applications to show to the user what the runner is currently
+ * capable of doing
+ */
+class PLASMA_EXPORT RunnerSyntax
+{
+    public:
+        /**
+         * Constructs a simple syntax object
+         *
+         * @arg exampleQuery an example of the query, with :q: placed wherever
+         *                   search term text might appear. e.g. if the runner
+         *                   accepts "keyword some random text" then the value
+         *                   of this parameter should be "keyword :q:"
+         * @arg descrition A description of what the described syntax does from
+         *                 the user's point of view.
+         */
+        RunnerSyntax(const QString &exampleQuery, const QString &description);
+
+        /**
+         * Copy constructor
+         */
+        RunnerSyntax(const RunnerSyntax &other);
+
+        /**
+         * Assignment operator
+         */
+        RunnerSyntax &operator=(const RunnerSyntax &rhs);
+
+        /**
+         * Adds a synonymous example query to this Syntax. Some runners may
+         * accept multiple formulations of keywords to trigger the same behaviour.
+         * This allows the runner to show these relationships by grouping the
+         * example queries into one Syntax object
+         *
+         * @arg exampleQuery an example of the query, with :q: placed wherever
+         *                   search term text might appear. e.g. if the runner
+         *                   accepts "keyword some random text" then the value
+         *                   of this parameter should be "keyword :q:"
+         */
+        void addExampleQuery(const QString &exampleQuery);
+
+        /**
+         * @return the example queries associated with this Syntax object
+         */
+        QStringList exampleQueries() const;
+
+        /**
+         * @return the example queries associated with this Syntax object, with
+         * the searchTermDescription replacing instances of :q:. Used for showing
+         * the queries in the user interface.
+         */
+        QStringList exampleQueriesWithTermDescription() const;
+
+        /**
+         * Sets the description for the syntax, describing what it does from
+         * the user's point of view.
+         */
+        void setDescription(const QString &description);
+
+        /**
+         * @return the description of what the syntax does from the user's
+         *         point of view
+         */
+        QString description() const;
+
+        /**
+         * Sets the text that should be used to replace instances of :q:
+         * in the text. By default this is the generic phrase "search term".
+         * If the syntax expects a specific kind of input, it may be defined
+         * here. A syntax used by a runner that changes the brightness of the display 
+         * may set this to "brightness" for instance.
+         */
+        void setSearchTermDescription(const QString &description);
+
+        /**
+         * @return a description of the search term for this syntax
+         */
+        QString searchTermDescription() const;
+
+    private:
+        RunnerSyntaxPrivate *const d;
+};
+
+} // namespace Plasma
+
+#endif // multiple inclusion guard
+