KRunner 5.109.0
runnermanager.h
1/*
2 SPDX-FileCopyrightText: 2006 Aaron Seigo <aseigo@kde.org>
3 SPDX-FileCopyrightText: 2007 Ryan P. Bitanga <ryan.bitanga@gmail.com>
4 SPDX-FileCopyrightText: 2008 Jordi Polo <mumismo@gmail.com>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef PLASMA_RUNNERMANAGER_H
10#define PLASMA_RUNNERMANAGER_H
11
12#include <QList>
13#include <QObject>
14
15#include "krunner_export.h"
16
17#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
18#include <KPluginInfo>
19#endif
20#include <KPluginMetaData>
21
22#include <memory>
23
24#include "abstractrunner.h"
25
26class QAction;
27class KConfigGroup;
28namespace
29{
30class AbstractRunnerTest;
31}
32
33namespace Plasma
34{
35class QueryMatch;
36class AbstractRunner;
37class RunnerContext;
38class RunnerManagerPrivate;
39
46class KRUNNER_EXPORT RunnerManager : public QObject
47{
48 Q_OBJECT
49 Q_PROPERTY(bool retainPriorSearch READ retainPriorSearch)
50 Q_PROPERTY(QString priorSearch READ priorSearch WRITE setPriorSearch)
51 Q_PROPERTY(QStringList history READ history)
52 Q_PROPERTY(bool historyEnabled READ historyEnabled NOTIFY historyEnabledChanged)
53
54public:
55 explicit RunnerManager(QObject *parent = nullptr);
56 explicit RunnerManager(const QString &configFile, QObject *parent = nullptr);
57#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
61 KRUNNER_DEPRECATED_VERSION(5, 76, "use RunnerManager(const QString &configFile, QObject *parent) instead")
62 explicit RunnerManager(KConfigGroup &config, QObject *parent = nullptr);
63#endif
64 ~RunnerManager() override;
65
71 AbstractRunner *runner(const QString &pluginName) const;
72
73#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 82)
79 KRUNNER_DEPRECATED_VERSION(5,
80 82,
81 "The dedicated singleRunnerMode methods are deprecated, use runner(const QString &pluginName) with the singleRunnerId instead")
82 AbstractRunner *singleModeRunner() const;
83
93 KRUNNER_DEPRECATED_VERSION(5,
94 82,
95 "The dedicated singleRunnerMode methods are deprecated, pass in the singleModeRunnerId into the launchQuery overload instead")
96 void setSingleModeRunnerId(const QString &id);
97
103 KRUNNER_DEPRECATED_VERSION(5, 82, "The dedicated singleRunnerMode methods are deprecated, save the variable before using it in launchQuery() instead")
104 QString singleModeRunnerId() const;
105
111 KRUNNER_DEPRECATED_VERSION(
112 5,
113 82,
114 "The dedicated singleRunnerMode methods are deprecated, call the RunnerContext::singleRunnerQueryMode on the searchContext instead")
115 bool singleMode() const;
116
125 KRUNNER_DEPRECATED_VERSION(5,
126 82,
127 "The dedicated singleRunnerMode methods are deprecated, the single mode is set to true when launchQuery is called with a non "
128 "empty and existing runnerId")
129 void setSingleMode(bool singleMode);
130
136 KRUNNER_DEPRECATED_VERSION(5, 81, "filter the runners manually using the X-Plasma-AdvertiseSingleRunnerQueryMode of the metadata")
137 QStringList singleModeAdvertisedRunnerIds() const;
138
146 KRUNNER_DEPRECATED_VERSION(5, 81, "call runner(const QString &id) and fetch the name from the returned object instead")
147 QString runnerName(const QString &id) const;
148#endif
149
153 QList<AbstractRunner *> runners() const;
154
160
165 QList<QueryMatch> matches() const;
166
171 void run(const QueryMatch &match);
172
173#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 79)
179 KRUNNER_DEPRECATED_VERSION(5, 79, "Use run(const QueryMatch &match) instead")
180 void run(const QString &id);
181#endif
182
190 bool runMatch(const QueryMatch &match);
191
195 QList<QAction *> actionsForMatch(const QueryMatch &match);
196
200 QString query() const;
201
207 QStringList history() const;
208
214 Q_INVOKABLE void removeFromHistory(int index);
215
222 Q_INVOKABLE QString getHistorySuggestion(const QString &typedQuery) const;
223
230 QString priorSearch() const;
231
236 void setPriorSearch(const QString &search);
237
243
249
254
261 void setAllowedRunners(const QStringList &runners);
262
263#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
270 KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused and not supported by most runners")
271 void setEnabledCategories(const QStringList &categories);
272#endif
273
274#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
275#if KSERVICE_BUILD_DEPRECATED_SINCE(5, 0)
287 KRUNNER_DEPRECATED_VERSION(5, 72, "use loadRunner(const KPluginMetaData &)")
288 void loadRunner(const KService::Ptr service);
289#endif
290#endif
291
302 void loadRunner(const KPluginMetaData &pluginMetaData);
303
304#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
315 KRUNNER_DEPRECATED_VERSION_BELATED(5, 77, 5, 0, "the KPackage support was removed in Plasma 5.0")
316 void loadRunner(const QString &path);
317#endif
318
319#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 88)
325 KRUNNER_DEPRECATED_VERSION(5, 88, "reading allowed runners from the config is deprecated, use runners() and get their ids instead")
326 QStringList allowedRunners() const;
327#endif
328
329#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
334 KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused and not supported by most runners")
335 QStringList enabledCategories() const;
336#endif
337
342 QMimeData *mimeDataForMatch(const QueryMatch &match) const;
343
344#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 79)
350 KRUNNER_DEPRECATED_VERSION(5, 79, "Use mimeDataForMatch(const QueryMatch &match) instead")
351 QMimeData *mimeDataForMatch(const QString &matchId) const;
352#endif
353
354#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 85)
367 KRUNNER_DEPRECATED_VERSION(5, 85, "The concept of parent apps for runners is deprecated, use no-arg overload instead")
368 static QVector<KPluginMetaData> runnerMetaDataList(const QString &parentApp);
369#endif
370
375 static QVector<KPluginMetaData> runnerMetaDataList();
376
377#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
390 KRUNNER_DEPRECATED_VERSION(5, 72, "Use runnerMetaDataList() instead")
391 static KPluginInfo::List listRunnerInfo(const QString &parentApp = QString());
392#endif
393
400 void enableKNotifyPluginWatcher(); // TODO KF6 make enabling the watcher default behavior and remove the method
401
402public Q_SLOTS:
411
419
429 void launchQuery(const QString &term, const QString &runnerId);
430
434 void launchQuery(const QString &term); // TODO KF6 Merge with other overload and use default argument
435
439 void reset();
440
441Q_SIGNALS:
445 void matchesChanged(const QList<Plasma::QueryMatch> &matches);
446
452
459 void setSearchTerm(const QString &term, int cursorPosition);
460
466
467private:
468 Q_PRIVATE_SLOT(d, void jobDone(ThreadWeaver::JobPointer))
469 KPluginMetaData convertDBusRunnerToJson(const QString &filename) const;
470 // exported for dbusrunnertest
471
472 std::unique_ptr<RunnerManagerPrivate> const d;
473
474 friend class RunnerManagerPrivate;
475 friend AbstractRunnerTest;
476};
477
478}
479#if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
480namespace KRunner
481{
482using RunnerManager = Plasma::RunnerManager;
483}
484#endif
485
486#endif
An abstract base class for Plasma Runner plugins.
Definition abstractrunner.h:69
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
QList< QAction * > actionsForMatch(const QueryMatch &match)
Retrieves the list of actions, if any, for a match.
void setAllowedRunners(const QStringList &runners)
Sets a whitelist for the plugins that can be loaded by this manager.
void setPriorSearch(const QString &search)
Set the prior search for this runner.
void matchesChanged(const QList< Plasma::QueryMatch > &matches)
Emitted each time a new match is added to the list.
bool retainPriorSearch()
If the prior search should be restored when KRunner is reopened.
void run(const QueryMatch &match)
Runs a given match.
static QVector< KPluginMetaData > runnerMetaDataList()
QList< AbstractRunner * > runners() const
AbstractRunner * runner(const QString &pluginName) const
Finds and returns a loaded runner or NULL.
void matchSessionComplete()
Call this method when the query session is finished for the time being.
QString query() const
void queryFinished()
Emitted when the launchQuery finish.
void enableKNotifyPluginWatcher()
If you call this method the manager will create a KConfigWatcher which reload its runners or the runn...
QList< QueryMatch > matches() const
Retrieves all available matches found so far for the previously launched query.
QString getHistorySuggestion(const QString &typedQuery) const
Get the suggested history entry for the typed query.
void reset()
Reset the current data and stops the query.
void removeFromHistory(int index)
Delete the given index from the history.
bool historyEnabled()
If history completion is enabled, the default value is true.
void setSearchTerm(const QString &term, int cursorPosition)
Put the given search term in the KRunner search field.
void reloadConfiguration()
Causes a reload of the current configuration.
QStringList history() const
QMimeData * mimeDataForMatch(const QueryMatch &match) const
bool runMatch(const QueryMatch &match)
Runs a given match.
void loadRunner(const KPluginMetaData &pluginMetaData)
Attempts to add the AbstractRunner plugin represented by the plugin info passed in.
RunnerContext * searchContext() const
Retrieves the current context.
void setupMatchSession()
Call this method when the runners should be prepared for a query session.
QString priorSearch() const
Get the suggested prior search for this runner.
void launchQuery(const QString &term, const QString &runnerId)
Launch a query, this will create threads and return immediately.
void launchQuery(const QString &term)
Convenience version of above.