diff --git a/CMakeLists.txt b/CMakeLists.txt index 79437fe9e..a9654131e 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/abstractrunner.cpp b/abstractrunner.cpp index 030b9cc36..60c29ef0f 100644 --- a/abstractrunner.cpp +++ b/abstractrunner.cpp @@ -26,6 +26,7 @@ #include #include +#include #include #include #include @@ -96,6 +97,7 @@ public: int fastRuns; Package *package; QHash actions; + QList 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 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(); } diff --git a/abstractrunner.h b/abstractrunner.h index 1cc244493..b9d428f54 100644 --- a/abstractrunner.h +++ b/abstractrunner.h @@ -28,8 +28,9 @@ #include #include -#include #include +#include +#include #include 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 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 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(); diff --git a/runnermanager.cpp b/runnermanager.cpp index daff45667..bdfc56f8c 100644 --- a/runnermanager.cpp +++ b/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 RunnerManager::runners() const +{ + return d->runners.values(); +} + RunnerContext* RunnerManager::searchContext() const { return &d->context; diff --git a/runnermanager.h b/runnermanager.h index 1a7ba4b13..04f9179de 100644 --- a/runnermanager.h +++ b/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 runners() const; + /** * Retrieves the current context * @return pointer to the current context diff --git a/runnersyntax.cpp b/runnersyntax.cpp new file mode 100644 index 000000000..3b9449e82 --- /dev/null +++ b/runnersyntax.cpp @@ -0,0 +1,105 @@ +/* + * Copyright 2009 Aaron Seigo + * + * 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 + +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 + diff --git a/runnersyntax.h b/runnersyntax.h new file mode 100644 index 000000000..33c6fd7b5 --- /dev/null +++ b/runnersyntax.h @@ -0,0 +1,124 @@ +/* + * Copyright 2009 Aaron Seigo + * + * 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 +#include + +#include + +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 +