7#ifndef PLASMA_ABSTRACTRUNNER_H
8#define PLASMA_ABSTRACTRUNNER_H
10#include "krunner_export.h"
15#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 94)
16#include <KConfigGroup>
22#include <KPluginMetaData>
24#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
28#include <KPluginFactory>
31#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65)
32#include <plasma/plasma_export.h>
33#include <plasma_version.h>
38#include "querymatch.h"
39#include "runnercontext.h"
40#include "runnersyntax.h"
44class QRegularExpression;
51class AbstractRunnerPrivate;
53enum RunnerReturnPluginMetaDataConstant { RunnerReturnPluginMetaData };
71 Q_PROPERTY(
bool matchingSuspended READ isMatchingSuspended WRITE suspendMatching NOTIFY matchingSuspended)
72 Q_PROPERTY(QString
id READ
id)
73 Q_PROPERTY(QString description READ description)
74 Q_PROPERTY(QString name READ name)
75 Q_PROPERTY(QIcon icon READ icon)
76 Q_PROPERTY(
int minLetterCount READ minLetterCount WRITE setMinLetterCount)
77 Q_PROPERTY(QRegularExpression matchRegex READ matchRegex WRITE setMatchRegex)
80#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
98 typedef QList<AbstractRunner *>
List;
153#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
162 KRUNNER_DEPRECATED_VERSION(5, 81,
"use match(Plasma::RunnerContext &context) instead")
166#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
173 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0,
"No longer use, feature removed")
174 bool hasRunOptions();
177#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 71)
186 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0,
"No longer use, feature removed")
187 virtual
void createRunOptions(QWidget *widget);
200#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
211 KRUNNER_DEPRECATED_VERSION(5, 76,
"Feature is unused")
212 virtual QStringList categories() const;
215#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
224 KRUNNER_DEPRECATED_VERSION_BELATED(5, 76, 5, 0,
"No longer use, feature removed")
225 virtual QIcon categoryIcon(const QString &category) const;
228#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
233 KRUNNER_DEPRECATED_VERSION(5, 81,
"the concept of delayed runners is deprecated, see method docs of setSpeed(Speed) for details")
243#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
250 KRUNNER_DEPRECATED_VERSION(5, 76,
"feature is deprecated")
254#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
274 KRUNNER_DEPRECATED_VERSION(5, 76,
"feature is deprecated. Consider using the minLetterCount and matchRegex properties instead")
293#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
298 KRUNNER_DEPRECATED_VERSION(5, 72,
"Use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs")
299 KPluginInfo metadata() const;
317#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
318 KPluginMetaData
metadata(RunnerReturnPluginMetaDataConstant)
const;
320 KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant = RunnerReturnPluginMetaData)
const;
327#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65)
328#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28)
338 KRUNNER_DEPRECATED_VERSION(5, 28, "No longer use, feature removed")
354#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
361 KRUNNER_DEPRECATED_VERSION(5, 76,
"No longer use, feature is unused")
455 friend class RunnerManagerPrivate;
464 AbstractRunner(QObject *parent,
const KPluginMetaData &pluginMetaData,
const QVariantList &args);
466#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
467 KRUNNER_DEPRECATED_VERSION(5, 77,
"use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
468 explicit
AbstractRunner(QObject *parent =
nullptr, const QString &path = QString());
470 explicit AbstractRunner(QObject *parent =
nullptr,
const QString &path = QString()) =
delete;
473#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
474#if KSERVICE_BUILD_DEPRECATED_SINCE(5, 0)
476 KRUNNER_DEPRECATED_VERSION(5, 72,
"use AbstractRunner(const KPluginMetaData &, QObject *)")
480#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
482 explicit AbstractRunner(
const KPluginMetaData &pluginMetaData, QObject *parent =
nullptr);
484#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
486 KRUNNER_DEPRECATED_VERSION(5, 77,
"use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
501#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
506 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0,
"No longer use, feature removed")
507 void setHasRunOptions(
bool hasRunOptions);
510#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
521 KRUNNER_DEPRECATED_VERSION(5, 81,
"the concept of delayed runners is deprecated, see method docs for porting instructions")
542#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
565 KRUNNER_DEPRECATED_VERSION(5, 86,
"create the QAction instance manually")
566 QAction *addAction(const QString &
id, const QIcon &icon, const QString &text);
578 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
579 void addAction(const QString &
id, QAction *action);
588 KRUNNER_DEPRECATED_VERSION(5, 86, "deprecated for lack of usage")
589 void removeAction(const QString &
id);
595 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead")
596 QAction *action(const QString &
id) const;
602 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead")
603 QHash<QString, QAction *> actions() const;
610 KRUNNER_DEPRECATED_VERSION(5, 86, "use a custom container to store the QAction instances instead")
624#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
640 KRUNNER_DEPRECATED_VERSION(5, 76,
"Feature unused, use addSyntax() instead")
649 inline void addSyntax(
const QString &exampleQuery,
const QString &description)
651 addSyntax(QStringList(exampleQuery), description);
655 inline void addSyntax(
const QStringList &exampleQueries,
const QString &description)
669#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 73)
690 KRUNNER_DEPRECATED_VERSION(5, 73,
"DataEngines are deprecated, use e.g. a shared library to provide the data instead.")
691 Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
709 std::unique_ptr<AbstractRunnerPrivate>
const d;
710 KRUNNER_NO_EXPORT
bool hasUniqueResults();
711 KRUNNER_NO_EXPORT
bool hasWeakResults();
713 friend class RunnerContextPrivate;
720#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
722#if KRUNNER_DEPRECATED_WARNINGS_SINCE >= 0x054800
723# if defined(__GNUC__)
724# define K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(x) _Pragma (#x)
725# define K_EXPORT_PLASMA_RUNNER_WARNING(x) K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(message(#x))
727# define K_EXPORT_PLASMA_RUNNER_WARNING(x)
730# define K_EXPORT_PLASMA_RUNNER_WARNING(x)
739#define K_EXPORT_PLASMA_RUNNER( libname, classname ) \
740K_EXPORT_PLASMA_RUNNER_WARNING("Deprecated. Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead") \
741K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
744#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 88)
756#define K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) \
757 K_PLUGIN_FACTORY_WITH_JSON(classname ## Factory, jsonFile, registerPlugin<classname>();)
760#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 75)
767#define K_EXPORT_RUNNER_CONFIG( name, classname ) \
768K_PLUGIN_FACTORY(ConfigFactory, registerPlugin<classname>();)
772#if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
An abstract base class for Plasma Runner plugins.
Definition abstractrunner.h:69
virtual QMimeData * mimeDataForMatch(const Plasma::QueryMatch &match)
Reimplement this slot if you want your runner to support serialization and drag and drop.
void matchingSuspended(bool suspended)
Emitted when the runner enters or exits match suspension.
QString description() const
void prepare()
This signal is emitted when matching is about to commence, giving runners an opportunity to prepare t...
void setMatchRegex(const QRegularExpression ®ex)
Set the matchRegex property.
virtual void reloadConfiguration()
Signal runner to reload its configuration.
Speed
Specifies a nominal speed for the runner.
Definition abstractrunner.h:82
virtual QList< QAction * > actionsForMatch(const Plasma::QueryMatch &match)
A given match can have more than action that can be performed on it.
void setTriggerWords(const QStringList &triggerWords)
Constructs internally a regex which requires the query to start with the trigger words.
void addSyntax(const QString &exampleQuery, const QString &description)
Utility overload for creating a syntax based on the given parameters.
Definition abstractrunner.h:649
void teardown()
This signal is emitted when a session of matches is complete, giving runners the opportunity to tear ...
Priority priority() const
The priority of the runner.
void suspendMatching(bool suspend)
Sets whether or not the runner is available for match requests.
virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match)
Called whenever an exact or possible match associated with this runner is triggered.
AbstractRunner(const KPluginMetaData &pluginMetaData, QObject *parent=nullptr)
virtual void init()
Reimplement this slot to run any initialization routines on first load.
QList< RunnerSyntax > syntaxes() const
void setMinLetterCount(int count)
Set the minLetterCount property.
int minLetterCount() const
This is the minimum letter count for the query.
QRegularExpression matchRegex() const
If this regex is set with a not empty pattern it must match the query in order for the performMatch/m...
Package package() const
Accessor for the associated Package object if any.
bool hasMatchRegex() const
If the runner has a valid regex and non empty regex.
void addSyntax(const RunnerSyntax &syntax)
Adds a registered syntax that this runner understands.
bool isMatchingSuspended() const
void setSyntaxes(const QList< RunnerSyntax > &syns)
Sets the list of syntaxes; passing in an empty list effectively clears the syntaxes.
void setPriority(Priority newPriority)
Sets the priority of the runner.
AbstractRunner(QObject *parent, const KPluginMetaData &pluginMetaData, const QVariantList &args)
Constructor for a KRunner plugin.
KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant) const
virtual void match(Plasma::RunnerContext &context)
This is the main query method.
QList< AbstractRunner * > List
An ordered list of runners.
Definition abstractrunner.h:98
Priority
Specifies a priority for the runner.
Definition abstractrunner.h:89
KConfigGroup config() const
Provides access to the runner's configuration object.
void addSyntax(const QStringList &exampleQueries, const QString &description)
Utility overload for creating a syntax based on the given parameters.
Definition abstractrunner.h:655
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition querymatch.h:35
The RunnerContext class provides information related to a search, including the search term,...
Definition runnercontext.h:32
The RunnerManager class decides what installed runners are runnable, and their ratings.
Definition runnermanager.h:47
Definition runnersyntax.h:42