KRunner 5.109.0
abstractrunner.h
1/*
2 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef PLASMA_ABSTRACTRUNNER_H
8#define PLASMA_ABSTRACTRUNNER_H
9
10#include "krunner_export.h"
11
12#include <QObject>
13#include <QStringList>
14
15#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 94)
16#include <KConfigGroup>
17#include <QIcon>
18#else
19class KConfigGroup;
20class QIcon;
21#endif
22#include <KPluginMetaData>
23
24#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
25#include <KPluginInfo>
26#include <KService>
27#else
28#include <KPluginFactory>
29#endif
30
31#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65)
32#include <plasma/plasma_export.h> // for PLASMA_ENABLE_DEPRECATED_SINCE
33#include <plasma_version.h>
34#endif
35
36#include <memory>
37
38#include "querymatch.h"
39#include "runnercontext.h"
40#include "runnersyntax.h"
41
42class QAction;
43class QMimeData;
44class QRegularExpression;
45
46namespace Plasma
47{
48class DataEngine;
49class Package;
50class QueryMatch;
51class AbstractRunnerPrivate;
52
53enum RunnerReturnPluginMetaDataConstant { RunnerReturnPluginMetaData }; // KF6: remove again
54
68class KRUNNER_EXPORT AbstractRunner : public QObject
69{
70 Q_OBJECT
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)
78
79public:
80#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
82 enum Speed{
83 SlowSpeed,
84 NormalSpeed,
85 };
86#endif
87
89 enum Priority {
90 LowestPriority = 0,
91 LowPriority,
92 NormalPriority,
93 HighPriority,
94 HighestPriority,
95 };
96
98 typedef QList<AbstractRunner *> List;
99
100 ~AbstractRunner() override;
101
151 virtual void match(Plasma::RunnerContext &context);
152
153#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
162 KRUNNER_DEPRECATED_VERSION(5, 81, "use match(Plasma::RunnerContext &context) instead")
163 void performMatch(Plasma::RunnerContext &context);
164#endif
165
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();
175#endif
176
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);
188#endif
189
198 virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match);
199
200#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
211 KRUNNER_DEPRECATED_VERSION(5, 76, "Feature is unused")
212 virtual QStringList categories() const;
213#endif
214
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;
226#endif
227
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")
234 Speed speed() const;
235#endif
236
242
243#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
250 KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated")
251 RunnerContext::Types ignoredTypes() const;
252#endif
253
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")
275 void setIgnoredTypes(RunnerContext::Types types);
276#endif
277
281 QString name() const;
282
286 QString id() const;
287
291 QString description() const;
292
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;
300#endif
301
317#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
318 KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant) const;
319#else
320 KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant = RunnerReturnPluginMetaData) const;
321#endif
325 QIcon icon() const;
326
327#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65) // not 5.28 here, this KRUNNER visibility control only added at 5.65
328#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28) // Plasma::Package is defined with this condition
338 KRUNNER_DEPRECATED_VERSION(5, 28, "No longer use, feature removed")
339 Package package() const;
340#endif
341#endif
342
346 virtual void reloadConfiguration();
347
352 QList<RunnerSyntax> syntaxes() const;
353
354#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
361 KRUNNER_DEPRECATED_VERSION(5, 76, "No longer use, feature is unused")
362 RunnerSyntax *defaultSyntax() const;
363#endif
364
371
382 int minLetterCount() const;
383
389 void setMinLetterCount(int count);
390
400 QRegularExpression matchRegex() const;
401
407 void setMatchRegex(const QRegularExpression &regex);
408
417 void setTriggerWords(const QStringList &triggerWords);
418
424 bool hasMatchRegex() const;
425
426Q_SIGNALS:
436 void prepare();
437
444 void teardown();
445
451 void matchingSuspended(bool suspended);
452
453protected:
454 friend class RunnerManager;
455 friend class RunnerManagerPrivate;
456
464 AbstractRunner(QObject *parent, const KPluginMetaData &pluginMetaData, const QVariantList &args);
465
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());
469#else
470 explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString()) = delete;
471#endif
472
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 *)")
477 explicit AbstractRunner(const KService::Ptr service, QObject *parent = nullptr);
478#endif
479#endif
480#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
482 explicit AbstractRunner(const KPluginMetaData &pluginMetaData, QObject *parent = nullptr);
483#endif
484#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
486 KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
487 AbstractRunner(QObject *parent, const QVariantList &args);
488#endif
489
494 void suspendMatching(bool suspend);
495
499 KConfigGroup config() const;
500
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);
508#endif
509
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")
522 void setSpeed(Speed newSpeed);
523#endif
524
529 void setPriority(Priority newPriority);
530
540 virtual QList<QAction *> actionsForMatch(const Plasma::QueryMatch &match);
541
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);
567
578 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
579 void addAction(const QString &id, QAction *action);
580
588 KRUNNER_DEPRECATED_VERSION(5, 86, "deprecated for lack of usage")
589 void removeAction(const QString &id);
590
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;
597
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;
604
610 KRUNNER_DEPRECATED_VERSION(5, 86, "use a custom container to store the QAction instances instead")
611 void clearActions();
612#endif
613
622 void addSyntax(const RunnerSyntax &syntax);
623
624#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
640 KRUNNER_DEPRECATED_VERSION(5, 76, "Feature unused, use addSyntax() instead")
641 void setDefaultSyntax(const RunnerSyntax &syntax);
642#endif
643
649 inline void addSyntax(const QString &exampleQuery, const QString &description)
650 {
651 addSyntax(QStringList(exampleQuery), description);
652 }
653
655 inline void addSyntax(const QStringList &exampleQueries, const QString &description)
656 {
657 addSyntax(RunnerSyntax(exampleQueries, description));
658 }
659
667 void setSyntaxes(const QList<RunnerSyntax> &syns);
668
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;
692#endif
693
699 virtual void init();
700
706 virtual QMimeData *mimeDataForMatch(const Plasma::QueryMatch &match);
707
708private:
709 std::unique_ptr<AbstractRunnerPrivate> const d;
710 KRUNNER_NO_EXPORT bool hasUniqueResults();
711 KRUNNER_NO_EXPORT bool hasWeakResults();
712 friend class RunnerContext;
713 friend class RunnerContextPrivate;
714 friend class QueryMatch;
715};
716
717} // Plasma namespace
718
719// clang-format off
720#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
721// Boilerplate to emit a version-controlled warning about the deprecated macro at least with GCC
722#if KRUNNER_DEPRECATED_WARNINGS_SINCE >= 0x054800 // 5.72.0
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))
726# else
727# define K_EXPORT_PLASMA_RUNNER_WARNING(x)
728# endif
729#else
730# define K_EXPORT_PLASMA_RUNNER_WARNING(x)
731#endif
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>();)
742#endif
743
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>();)
758#endif
759
760#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 75)
767#define K_EXPORT_RUNNER_CONFIG( name, classname ) \
768K_PLUGIN_FACTORY(ConfigFactory, registerPlugin<classname>();)
769#endif
770// clang-format on
771
772#if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
773namespace KRunner
774{
777}
778#endif
779
780#endif
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 &regex)
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.
QString id() const
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.
QString name() const
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