diff --git a/autotests/dbusrunnertest.cpp b/autotests/dbusrunnertest.cpp index 5349181..c78cf8c 100644 --- a/autotests/dbusrunnertest.cpp +++ b/autotests/dbusrunnertest.cpp @@ -1,118 +1,118 @@ /* * Copyright (C) 2017 David Edmundson * * 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 #include -#include +#include #include "runnermanager.h" #include #include #include #include using namespace Plasma; Q_DECLARE_METATYPE(Plasma::QueryMatch); Q_DECLARE_METATYPE(QList); class DBusRunnerTest : public QObject { Q_OBJECT public: DBusRunnerTest(); ~DBusRunnerTest(); private Q_SLOTS: void initTestCase(); void testMatch(); private: QProcess *m_process; }; DBusRunnerTest::DBusRunnerTest() : QObject(), m_process(new QProcess(this)) { m_process->start(QFINDTESTDATA("testremoterunner")); QVERIFY(m_process->waitForStarted()); qRegisterMetaType >(); } DBusRunnerTest::~DBusRunnerTest() { m_process->kill(); m_process->waitForFinished(); } void DBusRunnerTest::initTestCase() { QStandardPaths::setTestModeEnabled(true); QDir(QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation)).mkpath(QStringLiteral("kservices5")); const QString fakeServicePath = QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + QStringLiteral("/kservices5/dbusrunnertest.desktop"); QFile::copy(QFINDTESTDATA("dbusrunnertest.desktop"), fakeServicePath); KSycoca::self()->ensureCacheValid(); } void DBusRunnerTest::testMatch() { RunnerManager m; auto s = KService::serviceByDesktopPath(QStringLiteral("dbusrunnertest.desktop")); QVERIFY(s); m.loadRunner(s); m.launchQuery(QStringLiteral("foo")); QSignalSpy spy(&m, &RunnerManager::matchesChanged); QVERIFY(spy.wait()); //verify matches QCOMPARE(m.matches().count(), 1); auto result = m.matches().first(); //see testremoterunner.cpp QCOMPARE(result.id(), QStringLiteral("dbusrunnertest_id1")); //note the runner name is prepended QCOMPARE(result.text(), QStringLiteral("Match 1")); QCOMPARE(result.iconName(), QStringLiteral("icon1")); QCOMPARE(result.type(), Plasma::QueryMatch::ExactMatch); //relevance can't be compared easily becuase RunnerContext meddles with it //verify actions auto actions = m.actionsForMatch(result); QCOMPARE(actions.count(), 1); auto action = actions.first(); QCOMPARE(action->text(), QStringLiteral("Action 1")); QSignalSpy processSpy(m_process, &QProcess::readyRead); m.run(result); processSpy.wait(); QCOMPARE(m_process->readAllStandardOutput().trimmed(), QByteArray("Running:id1:")); result.setSelectedAction(action); m.run(result); processSpy.wait(); QCOMPARE(m_process->readAllStandardOutput().trimmed(), QByteArray("Running:id1:action1")); } QTEST_MAIN(DBusRunnerTest) #include "dbusrunnertest.moc" diff --git a/autotests/runnercontexttest.h b/autotests/runnercontexttest.h index 26a2518..da7abb7 100644 --- a/autotests/runnercontexttest.h +++ b/autotests/runnercontexttest.h @@ -1,39 +1,39 @@ /****************************************************************************** * Copyright 2010 Aaron Seigo * * * * 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 PACKAGEMETADATATEST_H -#include +#include #include "runnercontext.h" class RunnerContextTest : public QObject { Q_OBJECT private Q_SLOTS: void typeDetection_data(); void typeDetection(); private: Plasma::RunnerContext m_context; }; #endif diff --git a/src/abstractrunner.h b/src/abstractrunner.h index 0efecbd..a3cfe6f 100644 --- a/src/abstractrunner.h +++ b/src/abstractrunner.h @@ -1,493 +1,493 @@ /* * Copyright 2006-2007 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 Library 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_ABSTRACTRUNNER_H #define PLASMA_ABSTRACTRUNNER_H -#include -#include -#include +#include +#include +#include #include #include #include #include #include "krunner_export.h" #include "querymatch.h" #include "runnercontext.h" #include "runnersyntax.h" #include class QAction; class QMimeData; namespace Plasma { class DataEngine; class Package; class QueryMatch; class AbstractRunnerPrivate; /** * @class AbstractRunner abstractrunner.h * * @short An abstract base class for Plasma Runner plugins. * * Be aware that runners have to be thread-safe. This is due to the fact that * each runner is executed in its own thread for each new term. Thus, a runner * may be executed more than once at the same time. See match() for details. * To let krunner expose a global shortcut for the single runner query mode, the runner * must set the "X-Plasma-AdvertiseSingleRunnerMode" key to true in the .desktop file * and set a default syntax. See setDefaultSyntax() for details. * */ class KRUNNER_EXPORT AbstractRunner : public QObject { Q_OBJECT Q_PROPERTY(bool matchingSuspended READ isMatchingSuspended WRITE suspendMatching NOTIFY matchingSuspended) Q_PROPERTY(QString id READ id) Q_PROPERTY(QString description READ description) Q_PROPERTY(QString name READ name) Q_PROPERTY(QIcon icon READ icon) public: /** Specifies a nominal speed for the runner */ enum Speed { SlowSpeed, NormalSpeed }; /** Specifies a priority for the runner */ enum Priority { LowestPriority = 0, LowPriority, NormalPriority, HighPriority, HighestPriority }; /** An ordered list of runners */ typedef QList List; virtual ~AbstractRunner(); /** * This is the main query method. It should trigger creation of * QueryMatch instances through RunnerContext::addMatch and * RunnerContext::addMatches. It is called internally by performMatch(). * * If the runner can run precisely the requested term (RunnerContext::query()), * it should create an exact match by setting the type to RunnerContext::ExactMatch. * The first runner that creates a QueryMatch will be the * default runner. Other runner's matches will be suggested in the * interface. Non-exact matches should be offered via RunnerContext::PossibleMatch. * * The match will be activated via run() if the user selects it. * * Each runner is executed in its own thread. Whenever the user input changes this * method is called again. Thus, it needs to be thread-safe. Also, all matches need * to be reported once this method returns. Asynchronous runners therefore need * to make use of a local event loop to wait for all matches. * * It is recommended to use local status data in async runners. The simplest way is * to have a separate class doing all the work like so: * * \code * void MyFancyAsyncRunner::match( RunnerContext& context ) * { * QEventLoop loop; * MyAsyncWorker worker( context ); * connect( &worker, SIGNAL(finished()), * &loop, SLOT(quit()) ); * worker.work(); * loop.exec(); * } * \endcode * * Here MyAsyncWorker creates all the matches and calls RunnerContext::addMatch * in some internal slot. It emits the finished() signal once done which will * quit the loop and make the match() method return. The local status is kept * entirely in MyAsyncWorker which makes match() trivially thread-safe. * * If a particular match supports multiple actions, set up the corresponding * actions in the actionsForMatch method. Do not call any of the action methods * within this method! * * Execution of the correct action should be handled in the run method. * @caution This method needs to be thread-safe since KRunner will simply * start a new thread for each new term. * * @warning Returning from this method means to end execution of the runner. * * @sa run(), RunnerContext::addMatch, RunnerContext::addMatches, QueryMatch */ virtual void match(Plasma::RunnerContext &context); /** * Triggers a call to match. This will call match() internally. * * @param context the search context used in executing this match. */ void performMatch(Plasma::RunnerContext &context); /** * If the runner has options that the user can interact with to modify * what happens when run or one of the actions created in match * is called, the runner should return true */ bool hasRunOptions(); /** * If hasRunOptions() returns true, this method may be called to get * a widget displaying the options the user can interact with to modify * the behaviour of what happens when a given match is selected. * * @param widget the parent of the options widgets. */ virtual void createRunOptions(QWidget *widget); /** * Called whenever an exact or possible match associated with this * runner is triggered. * * @param context The context in which the match is triggered, i.e. for which * the match was created. * @param match The actual match to run/execute. */ virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match); /** * Return a list of categories that this runner provides. By default * this list just contains the runners name. It is used by the runner manager * to disable certain runners if all the categories they provide have * been disabled. * * This list of categories is also used to provide a better way to * configure the runner instead of the typical on / off switch. */ virtual QStringList categories() const; /** * Returns the icon which accurately describes the category \p category. * This is meant to be used in a configuration dialog when showing * all the categories. * * By default this returns the icon of the AbstractRunner */ virtual QIcon categoryIcon(const QString& category) const; /** * The nominal speed of the runner. * @see setSpeed */ Speed speed() const; /** * The priority of the runner. * @see setPriority */ Priority priority() const; /** * Returns the OR'ed value of all the Information types (as defined in RunnerContext::Type) * this runner is not interested in. * @return OR'ed value of black listed types */ RunnerContext::Types ignoredTypes() const; /** * Sets the types this runner will ignore * @param types OR'ed listed of ignored types */ void setIgnoredTypes(RunnerContext::Types types); /** * @return the user visible engine name for the Runner */ QString name() const; /** * @return an id string for the Runner */ QString id() const; /** * @return the description of this Runner */ QString description() const; /** * @return the plugin info for this runner */ KPluginInfo metadata() const; /** * @return the icon for this Runner */ QIcon icon() const; /** * Accessor for the associated Package object if any. * * Note that the returned pointer is only valid for the lifetime of * the runner. * * @return the Package object, which may be invalid **/ Package package() const; /** * Signal runner to reload its configuration. */ virtual void reloadConfiguration(); /** * @return the syntaxes the runner has registered that it accepts and understands * @since 4.3 */ QList syntaxes() const; /** * @return the default syntax for the runner or 0 if no default syntax has been defined * * @since 4.4 */ RunnerSyntax *defaultSyntax() const; /** * @return true if the runner is currently busy with non-interuptable work, signaling that * new threads should not be created for it at this time * @since 4.6 */ bool isMatchingSuspended() const; Q_SIGNALS: /** * This signal is emitted when matching is about to commence, giving runners * an opportunity to prepare themselves, e.g. loading data sets or preparing * IPC or network connections. This method should be fast so as not to cause * slow downs. Things that take longer or which should be loaded once and * remain extant for the lifespan of the AbstractRunner should be done in init(). * @see init() * @since 4.4 */ void prepare(); /** * This signal is emitted when a session of matches is complete, giving runners * the opportunity to tear down anything set up as a result of the prepare() * method. * @since 4.4 */ void teardown(); /** * Emitted when the runner enters or exits match suspension * @see matchingSuspended * @since 4.6 */ void matchingSuspended(bool suspended); protected: friend class RunnerManager; friend class RunnerManagerPrivate; explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString()); explicit AbstractRunner(const KService::Ptr service, QObject *parent = nullptr); AbstractRunner(QObject *parent, const QVariantList &args); /** * Sets whether or not the runner is available for match requests. Useful to * prevent more thread spawning when the thread is in a busy state. */ void suspendMatching(bool suspend); /** * Provides access to the runner's configuration object. */ KConfigGroup config() const; /** * Sets whether or not the runner has options for matches */ void setHasRunOptions(bool hasRunOptions); /** * Sets the nominal speed of the runner. Only slow runners need * to call this within their constructor because the default * speed is NormalSpeed. Runners that use D-Bus should call * this within their constructors. */ void setSpeed(Speed newSpeed); /** * Sets the priority of the runner. Lower priority runners are executed * only after higher priority runners. */ void setPriority(Priority newPriority); /** * A given match can have more than action that can be performed on it. * For example, a song match returned by a music player runner can be queued, * added to the playlist, or played. * * Call this method to add actions that can be performed by the runner. * Actions must first be added to the runner's action registry. * Note: execution of correct action is left up to the runner. */ virtual QList actionsForMatch(const Plasma::QueryMatch &match); /** * Creates and then adds an action to the action registry. * AbstractRunner assumes ownership of the created action. * * @param id A unique identifier string * @param icon The icon to display * @param text The text to display * @return the created QAction */ QAction* addAction(const QString &id, const QIcon &icon, const QString &text); /** * Adds an action to the runner's action registry. * * The QAction must be created within the GUI thread; * do not create it within the match method of AbstractRunner. * * @param id A unique identifier string * @param action The QAction to be stored */ void addAction(const QString &id, QAction *action); /** * Removes the action from the action registry. * AbstractRunner deletes the action once removed. * * @param id The id of the action to be removed */ void removeAction(const QString &id); /** * Returns the action associated with the id */ QAction* action(const QString &id) const; /** * Returns all registered actions */ QHash actions() const; /** * Clears the action registry. * The action pool deletes the actions. */ void clearActions(); /** * Adds a registered syntax that this runner understands. This is used to * display to the user what this runner can understand and how it can be * used. * * @param syntax the syntax to register * @since 4.3 */ void addSyntax(const RunnerSyntax &syntax); /** * Set @p syntax as the default syntax for the runner; the default syntax will be * substituted to the empty query in single runner mode. This is also used to * display to the user what this runner can understand and how it can be * used. * The default syntax is automatically added to the list of registered syntaxes, there * is no need to add it using addSyntax. * Note that there can be only one default syntax; if called more than once, the last * call will determine the default syntax. * A default syntax (even trivial) is required to advertise single runner mode * * @param syntax the syntax to register and to set as default * @since 4.4 **/ void setDefaultSyntax(const RunnerSyntax &syntax); /** * Sets the list of syntaxes; passing in an empty list effectively clears * the syntaxes. * * @param the syntaxes to register for this runner * @since 4.3 */ void setSyntaxes(const QList &syns); /** * Loads the given DataEngine * * Tries to load the data engine given by @p name. Each engine is * only loaded once, and that instance is re-used on all subsequent * requests. * * If the data engine was not found, an invalid data engine is returned * (see DataEngine::isValid()). * * Note that you should not delete the returned engine. * * @param name Name of the data engine to load * @return pointer to the data engine if it was loaded, * or an invalid data engine if the requested engine * could not be loaded * * @since 4.4 */ Q_INVOKABLE DataEngine *dataEngine(const QString &name) const; /** * Reimplement this slot to run any initialization routines on first load. * By default, it calls reloadConfiguration(); for scripted Runners this * method also sets up the ScriptEngine. */ virtual void init(); /** * Reimplement this slot if you want your runner * to support serialization and drag and drop * @since 4.5 */ virtual QMimeData *mimeDataForMatch(const Plasma::QueryMatch &match); private: AbstractRunnerPrivate *const d; }; } // Plasma namespace #define K_EXPORT_PLASMA_RUNNER( libname, classname ) \ K_PLUGIN_FACTORY(factory, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) /** * These plugins are Used by the plugin selector dialog to show * configuration options specific to this runner. These options * must be runner global and not pertain to a specific match. */ #define K_EXPORT_RUNNER_CONFIG( name, classname ) \ K_PLUGIN_FACTORY(ConfigFactory, registerPlugin();) \ K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) #endif diff --git a/src/querymatch.h b/src/querymatch.h index ff272b6..62538ce 100644 --- a/src/querymatch.h +++ b/src/querymatch.h @@ -1,312 +1,312 @@ /* * Copyright 2006-2007 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_QUERYMATCH_H #define PLASMA_QUERYMATCH_H -#include -#include -#include +#include +#include +#include #include "krunner_export.h" class QAction; class QIcon; class QString; class QVariant; class QWidget; namespace Plasma { class RunnerContext; class AbstractRunner; class QueryMatchPrivate; /** * @class QueryMatch querymatch.h * * @short A match returned by an AbstractRunner in response to a given * RunnerContext. */ class KRUNNER_EXPORT QueryMatch { public: /** * The type of match. Value is important here as it is used for sorting */ enum Type { NoMatch = 0, /**< Null match */ CompletionMatch = 10, /**< Possible completion for the data of the query */ PossibleMatch = 30, /**< Something that may match the query */ InformationalMatch = 50, /**< A purely informational, non-actionable match, such as the answer to a question or calculation*/ HelperMatch = 70, /**< A match that represents an action not directly related to activating the given search term, such as a search in an external tool or a command learning trigger. Helper matches tend to be generic to the query and should not be autoactivated just because the user hits "Enter" while typing. They must be explicitly selected to be activated, but unlike InformationalMatch cause an action to be triggered. */ ExactMatch = 100 /**< An exact match to the query */ }; /** * Constructs a PossibleMatch associated with a given RunnerContext * and runner. * * @param runner the runner this match belongs to */ explicit QueryMatch(AbstractRunner *runner = nullptr); /** * Copy constructor */ QueryMatch(const QueryMatch &other); ~QueryMatch(); QueryMatch &operator=(const QueryMatch &other); bool operator==(const QueryMatch &other) const; bool operator!=(const QueryMatch &other) const; bool operator<(const QueryMatch &other) const; /** * @return the runner associated with this action */ AbstractRunner *runner() const; /** * Requests this match to activae using the given context * * @param context the context to use in conjunction with this run * * @sa AbstractRunner::run */ void run(const RunnerContext &context) const; /** * @return true if the match is valid and can therefore be run, * an invalid match does not have an associated AbstractRunner */ bool isValid() const; /** * Sets the type of match this action represents. */ void setType(Type type); /** * The type of action this is. Defaults to PossibleMatch. */ Type type() const; /** * Sets information about the type of the match which can * be used to categorize the match. * * This string should be translated as it can be displayed * in an UI */ void setMatchCategory(const QString& category); /** * Extra information about the match which can be used * to categorize the type. * * By default this returns the internal name of the runner * which returned this result */ QString matchCategory() const; /** * Sets the relevance of this action for the search * it was created for. * * @param relevance a number between 0 and 1. */ void setRelevance(qreal relevance); /** * The relevance of this action to the search. By default, * the relevance is 1. * * @return a number between 0 and 1 */ qreal relevance() const; /** * Sets data to be used internally by the associated * AbstractRunner. * * When set, it is also used to form * part of the id() for this match. If that is innapropriate * as an id, the runner may generate its own id and set that * with setId(const QString&) directly after calling setData */ void setData(const QVariant &data); /** * @return the data associated with this match; usually runner-specific */ QVariant data() const; /** * Sets the id for this match; useful if the id does not * match data().toString(). The id must be unique to all * matches from this runner, and should remain constant * for the same query for best results. * * @param id the new identifying string to use to refer * to this entry */ void setId(const QString &id); /** * @return a string that can be used as an ID for this match, * even between different queries. It is based in part * on the source of the match (the AbstractRunner) and * distinguishing information provided by the runner, * ensuring global uniqueness as well as consistency * between query matches. */ QString id() const; /** * Sets the main title text for this match; should be short * enough to fit nicely on one line in a user interface * * @param text the text to use as the title */ void setText(const QString &text); /** * @return the title text for this match */ QString text() const; /** * Sets the descriptive text for this match; can be longer * than the main title text * * @param text the text to use as the description */ void setSubtext(const QString &text); /** * @return the descriptive text for this match */ QString subtext() const; /** * Sets the icon associated with this match * * Prefer using setIconName. * * @param icon the icon to show along with the match */ void setIcon(const QIcon &icon); /** * @return the icon for this match */ QIcon icon() const; /** * Sets the icon name associated with this match * * @param icon the name of the icon to show along with the match * @since 5.24 */ void setIconName(const QString &iconName); /** * @return the name of the icon for this match * @since 5.24 */ QString iconName() const; /** * Sets the MimeType, if any, associated with this match. * This overrides the MimeType provided by QueryContext, and should only be * set when it is different from the QueryContext MimeType */ void setMimeType(const QString &mimeType); /** * @return the mimtype for this match, or QString() is none */ QString mimeType() const; /** * Sets the urls, if any, associated with this match */ void setUrls(const QList &urls); /** * @return the mimtype for this match, or QString() is none */ QList urls() const; /** * Sets whether or not this match can be activited * * @param enable true if the match is enabled and therefore runnable */ void setEnabled(bool enable); /** * @return true if the match is enabled and therefore runnable, otherwise false */ bool isEnabled() const; /** * The current action. */ QAction* selectedAction() const; /** * Sets the selected action */ void setSelectedAction(QAction *action); /** * @return true if this match can be configured before being run * @since 4.3 */ bool hasConfigurationInterface() const; /** * If hasConfigurationInterface() returns true, this method may be called to get * a widget displaying the options the user can interact with to modify * the behaviour of what happens when the match is run. * * @param widget the parent of the options widgets. * @since 4.3 */ void createConfigurationInterface(QWidget *parent); private: QSharedDataPointer d; }; } #endif diff --git a/src/runnercontext.h b/src/runnercontext.h index 1e4b334..bae1919 100644 --- a/src/runnercontext.h +++ b/src/runnercontext.h @@ -1,269 +1,269 @@ /* * Copyright 2006-2007 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_RUNNERCONTEXT_H #define PLASMA_RUNNERCONTEXT_H -#include -#include -#include +#include +#include +#include #include "krunner_export.h" class KConfigGroup; namespace Plasma { class QueryMatch; class AbstractRunner; class RunnerContextPrivate; /** * @class RunnerContext runnercontext.h * * @short The RunnerContext class provides information related to a search, * including the search term, metadata on the search term and collected * matches. */ class KRUNNER_EXPORT RunnerContext : public QObject { Q_OBJECT public: enum Type { None = 0, UnknownType = 1, Directory = 2, File = 4, NetworkLocation = 8, Executable = 16, ShellCommand = 32, Help = 64, FileSystem = Directory | File | Executable | ShellCommand }; Q_DECLARE_FLAGS(Types, Type) explicit RunnerContext(QObject *parent = nullptr); /** * Copy constructor */ RunnerContext(RunnerContext &other, QObject *parent = nullptr); /** * Assignment operator * @since 4.4 */ RunnerContext &operator=(const RunnerContext &other); ~RunnerContext(); /** * Resets the search term for this object. * This removes all current matches in the process and * turns off single runner query mode. */ void reset(); /** * Sets the query term for this object and attempts to determine * the type of the search. */ void setQuery(const QString &term); /** * @return the current search query term. */ QString query() const; /** * The type of item the search term might refer to. * @see Type */ Type type() const; /** * A list of categories of which results should be returned. * This list is typically populated from the AbstractRunner::categories * function. */ QStringList enabledCategories() const; /** * Sets the list of enabled categories. Runners can use this list * to optimize themselves by only returning results from the enabled * categories */ void setEnabledCategories(const QStringList &categories); /** * The mimetype that the search term refers to, if discoverable. * * @return QString() if the mimetype can not be determined, otherwise * the mimetype of the object being referred to by the search * string. */ QString mimeType() const; /** * @returns true if this context is no longer valid and therefore * matching using it should abort. Most useful as an optimization technique * inside of AbstractRunner subclasses in the match method, e.g.: * * while (.. a possibly large iteration) { * if (!context.isValid()) { * return; * } * * ... some processing ... * } * * While not required to be used within runners, it provies a nice way * to avoid unnecessary processing in runners that may run for an extended * period (as measured in 10s of ms) and therefore improve the user experience. * @since 4.2.3 */ bool isValid() const; /** * Appends lists of matches to the list of matches. * * @param matches the matches to add * @return true if matches were added, false if matches were e.g. outdated */ bool addMatches(const QList &matches); /** * Appends a match to the existing list of matches. * * If you are going to be adding multiple matches, use @see addMatches instead. * * @param match the match to add * @return true if the match was added, false otherwise. */ bool addMatch(const QueryMatch &match); /** * Removes a match from the existing list of matches. * * If you are going to be removing multiple matches, use removeMatches instead. * * @param matchId the id of match to remove * * @return true if the match was removed, false otherwise. * @since 4.4 */ bool removeMatch(const QString matchId); /** * Removes lists of matches from the existing list of matches. * * This method is thread safe and causes the matchesChanged() signal to be emitted. * * @param matchIdList the list of matches id to remove * * @return true if at least one match was removed, false otherwise. * @since 4.4 */ bool removeMatches(const QStringList matchIdList); /** * Removes lists of matches from a given AbstractRunner * * This method is thread safe and causes the matchesChanged() signal to be emitted. * * @param runner the AbstractRunner from which to remove matches * * @return true if at least one match was removed, false otherwise. * @since 4.10 */ bool removeMatches(AbstractRunner *runner); /** * Retrieves all available matches for the current search term. * * @return a list of matches */ QList matches() const; /** * Retrieves a match by id. * * @param id the id of the match to return * @return the match associated with this id, or an invalid QueryMatch object * if the id does not eixst */ QueryMatch match(const QString &id) const; /** * Sets single runner query mode. Note that a call to reset() will * turn off single runner query mode. * * @see reset() * @since 4.4 */ void setSingleRunnerQueryMode(bool enabled); /** * @return true if the current query is a single runner query * @since 4.4 */ bool singleRunnerQueryMode() const; /** * Sets the launch counts for the associated match ids * * If a runner adds a match to this context, the context will check if the * match id has been launched before and increase the matches relevance * correspondingly. In this manner, any front end can implement adaptive search * by sorting items according to relevance. * * @param config the config group where launch data was stored */ void restore(const KConfigGroup &config); /** * @param config the config group where launch data should be stored */ void save(KConfigGroup &config); /** * Run a match using the information from this context * * The context will also keep track of the number of times the match was * launched to sort future matches according to user habits * * @param match the match to run */ void run(const QueryMatch &match); Q_SIGNALS: void matchesChanged(); private: QExplicitlySharedDataPointer d; }; } Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::RunnerContext::Types) #endif diff --git a/src/runnermanager.h b/src/runnermanager.h index 5c47e70..50555b9 100644 --- a/src/runnermanager.h +++ b/src/runnermanager.h @@ -1,299 +1,299 @@ /* * Copyright (C) 2006 Aaron Seigo * Copyright (C) 2007 Ryan P. Bitanga * Copyright (C) 2008 Jordi Polo * * 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_RUNNERMANAGER_H #define PLASMA_RUNNERMANAGER_H -#include -#include +#include +#include #include #include "krunner_export.h" #include "abstractrunner.h" class QAction; class KConfigGroup; namespace Plasma { class QueryMatch; class AbstractRunner; class RunnerContext; class RunnerManagerPrivate; /** * @class RunnerManager runnermanager.h * * @short The RunnerManager class decides what installed runners are runnable, * and their ratings. It is the main proxy to the runners. */ class KRUNNER_EXPORT RunnerManager : public QObject { Q_OBJECT public: explicit RunnerManager(QObject *parent=nullptr); explicit RunnerManager(KConfigGroup &config, QObject *parent=nullptr); ~RunnerManager(); /** * Finds and returns a loaded runner or NULL * @param pluginName the name of the runner plugin * @return Pointer to the runner */ AbstractRunner *runner(const QString &pluginName) const; /** * @return the currently active "single mode" runner, or null if none * @since 4.4 */ AbstractRunner *singleModeRunner() const; /** * Puts the manager into "single runner" mode using the given * runner; if the runner does not exist or can not be loaded then * the single runner mode will not be started and singleModeRunner() * will return NULL * @param id the id of the runner to use * @since 4.4 */ void setSingleModeRunnerId(const QString &id); /** * @return the id of the runner to use in single mode * @since 4.4 */ QString singleModeRunnerId() const; /** * @return true if the manager is set to run in single runner mode * @since 4.4 */ bool singleMode() const; /** * Sets whether or not the manager is in single mode. * * @param singleMode true if the manager should be in single mode, false otherwise * @since 4.4 */ void setSingleMode(bool singleMode); /** * Returns the translated name of a runner * @param id the id of the runner * * @since 4.4 */ QString runnerName(const QString &id) const; /** * @return the list of all currently loaded runners */ QList runners() const; /** * @return the names of all runners that advertise single query mode * @since 4.4 */ QStringList singleModeAdvertisedRunnerIds() const; /** * Retrieves the current context * @return pointer to the current context */ RunnerContext *searchContext() const; /** * Retrieves all available matches found so far for the previously launched query * @return List of matches */ QList matches() const; /** * Runs a given match * @param match the match to be executed */ void run(const QueryMatch &match); /** * Runs a given match * @param id the id of the match to run */ void run(const QString &id); /** * Retrieves the list of actions, if any, for a match */ QList actionsForMatch(const QueryMatch &match); /** * @return the current query term */ QString query() const; /** * Causes a reload of the current configuration */ void reloadConfiguration(); /** * Sets a whitelist for the plugins that can be loaded * * @param plugins the plugin names of allowed runners * @since 4.4 */ void setAllowedRunners(const QStringList &runners); /** * Sets the list of categories which matches should be * returned for. It also internally tries not to execute the * runners which do not fall in this category. */ void setEnabledCategories(const QStringList &categories); /** * Attempts to add the AbstractRunner plugin represented * by the KService passed in. Usually one can simply let * the configuration of plugins handle loading Runner plugins, * but in cases where specific runners should be loaded this * allows for that to take place * * @param service the service to use to load the plugin * @since 4.5 */ void loadRunner(const KService::Ptr service); /** * Attempts to add the AbstractRunner from a Plasma::Package on disk. * Usually one can simply let the configuration of plugins * handle loading Runner plugins, but in cases where specific * runners should be loaded this allows for that to take place * * @param path the path to a Runner package to load * @since 4.5 */ void loadRunner(const QString &path); /** * @return the list of allowed plugins * @since 4.4 */ QStringList allowedRunners() const; /** * @return the list of enabled categories */ QStringList enabledCategories() const; /** * @return mime data of the specified match * @since 4.5 */ QMimeData * mimeDataForMatch(const QueryMatch &match) const; /** * @return mime data of the specified match * @since 4.5 */ QMimeData * mimeDataForMatch(const QString &matchId) const; /** * Returns a list of all known Runner implementations * * @param parentApp the application to filter applets on. Uses the * X-KDE-ParentApp entry (if any) in the plugin info. * The default value of QString() will result in a * list containing only applets not specifically * registered to an application. * @return list of AbstractRunners * @since 4.6 **/ static KPluginInfo::List listRunnerInfo(const QString &parentApp = QString()); public Q_SLOTS: /** * Call this method when the runners should be prepared for a query session. * Call matchSessionComplete when the query session is finished for the time * being. * @since 4.4 * @see matchSessionComplete */ void setupMatchSession(); /** * Call this method when the query session is finished for the time * being. * @since 4.4 * @see prepareForMatchSession */ void matchSessionComplete(); /** * Launch a query, this will create threads and return inmediately. * When the information will be available can be known using the * matchesChanged signal. * * @param term the term we want to find matches for * @param runnerId optional, if only one specific runner is to be used; * providing an id will put the manager into single runner mode */ void launchQuery(const QString &term, const QString &runnerId); /** * Convenience version of above */ void launchQuery(const QString &term); /** * Reset the current data and stops the query */ void reset(); Q_SIGNALS: /** * Emitted each time a new match is added to the list */ void matchesChanged(const QList &matches); /** * Emitted when the launchQuery finish * @since 4.5 */ void queryFinished(); private: Q_PRIVATE_SLOT(d, void scheduleMatchesChanged()) Q_PRIVATE_SLOT(d, void matchesChanged()) Q_PRIVATE_SLOT(d, void jobDone(ThreadWeaver::JobPointer)) Q_PRIVATE_SLOT(d, void unblockJobs()) Q_PRIVATE_SLOT(d, void runnerMatchingSuspended(bool)) RunnerManagerPrivate * const d; friend class RunnerManagerPrivate; }; } #endif diff --git a/src/runnersyntax.h b/src/runnersyntax.h index 9c0164f..661e3f2 100644 --- a/src/runnersyntax.h +++ b/src/runnersyntax.h @@ -1,125 +1,125 @@ /* * 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 "krunner_export.h" namespace Plasma { class RunnerSyntaxPrivate; /** * @class RunnerSyntax runnersyntax.h * @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 KRUNNER_EXPORT RunnerSyntax { public: /** * Constructs a simple syntax object * * @param 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:" * @param 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); ~RunnerSyntax(); /** * 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 * * @param 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