alecs/plasma-framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
svn path=/trunk/KDE/kdelibs/; revision=944088
This commit is contained in:
Aaron J. Seigo 2009-03-25 01:08:08 +00:00
parent 4f20cfe5a6
commit acaa4108df
7 changed files with 310 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CMakeLists.txt
View File

@ -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

28
abstractrunner.cpp
View File

@ -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();
}

37
abstractrunner.h
View File

@ -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();

14
runnermanager.cpp
View File

@ -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;

5
runnermanager.h
View File

@ -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

105
runnersyntax.cpp Normal file
View File

@ -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

124
runnersyntax.h Normal file
View File

@ -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