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 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnauŋmx.de>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#ifndef KRUNNER_RUNNERMANAGER_H
11#define KRUNNER_RUNNERMANAGER_H
12
13#include <QList>
14#include <QObject>
15
16#include <KPluginMetaData>
17
18#include "abstractrunner.h"
19#include "action.h"
20#include "krunner_export.h"
21#include <memory>
22
23class KConfigGroup;
24namespace KRunner
25{
26class AbstractRunnerTest;
27}
28
29namespace KRunner
30{
31class QueryMatch;
32class AbstractRunner;
33class RunnerContext;
34class RunnerManagerPrivate;
35
36/**
37 * @class RunnerManager runnermanager.h <KRunner/RunnerManager>
38 *
39 * @short The RunnerManager class decides what installed runners are runnable,
40 * and their ratings. It is the main proxy to the runners.
41 */
42class KRUNNER_EXPORT RunnerManager : public QObject
43{
44 Q_OBJECT
45 Q_PROPERTY(QStringList history READ history)
46 Q_PROPERTY(bool historyEnabled READ historyEnabled WRITE setHistoryEnabled NOTIFY historyEnabledChanged)
47
48public:
49 /**
50 * Constructs a RunnerManager with the given parameters
51 * @param configurationGroup Config group used for reading enabled plugins
52 * @param stateGroup Config group used for storing history
53 * @since 6.0
54 */
55 explicit RunnerManager(const KConfigGroup &pluginConfigGroup, KConfigGroup stateGroup, QObject *parent);
56
57 /**
58 * Constructs a RunnerManager using the default locations for state/plugin config
59 */
60 explicit RunnerManager(QObject *parent = nullptr);
61 ~RunnerManager() override;
62
63 /**
64 * Finds and returns a loaded runner or a nullptr
65 * @param pluginId the name of the runner plugin
66 * @return Pointer to the runner
67 */
68 AbstractRunner *runner(const QString &pluginId) const;
69
70 /**
71 * @return the list of all currently loaded runners
72 */
73 QList<AbstractRunner *> runners() const;
74
75 /**
76 * Retrieves the current context
77 * @return pointer to the current context
78 */
79 RunnerContext *searchContext() const;
80
81 /**
82 * Retrieves all available matches found so far for the previously launched query
83 * @return List of matches
84 */
85 QList<QueryMatch> matches() const;
86
87 /**
88 * Runs a given match. This also respects the extra handling for the InformationalMatch.
89 * This also handles the history automatically
90 * @param match the match to be executed
91 * @param selectedAction the action returned by @ref QueryMatch::actions that has been selected by the user, nullptr if none
92 * @return if the RunnerWindow should close
93 * @since 6.0
94 */
95 bool run(const QueryMatch &match, const KRunner::Action &action = {});
96
97 /**
98 * @return the current query term set in @ref launchQuery
99 */
100 QString query() const;
101
102 /**
103 * @return History of this runner for the current activity. If the RunnerManager is not history
104 * aware the global entries will be returned.
105 * @since 5.78
106 */
107 QStringList history() const;
108
109 /**
110 * Delete the given index from the history.
111 * @param historyEntry
112 * @since 5.78
113 */
114 Q_INVOKABLE void removeFromHistory(int index);
115
116 /**
117 * Get the suggested history entry for the typed query. If no entry is found an empty string is returned.
118 * @param typedQuery
119 * @return completion for typedQuery
120 * @since 5.78
121 */
122 Q_INVOKABLE QString getHistorySuggestion(const QString &typedQuery) const;
123
124 /**
125 * If history completion is enabled, the default value is true.
126 * @since 5.78
127 */
128 bool historyEnabled();
129
130 /**
131 * Enables/disabled the history feature for the RunnerManager instance.
132 * The value will not be persisted and is only kept during the object's lifetime.
133 *
134 * @since 6.0
135 */
136 void setHistoryEnabled(bool enabled);
137
138 /**
139 * Causes a reload of the current configuration
140 * This gets called automatically when the config in the KCM is saved
141 */
142 void reloadConfiguration();
143
144 /**
145 * Sets a whitelist for the plugins that can be loaded by this manager.
146 * Runners that are disabled through the config will not be loaded.
147 *
148 * @param plugins the plugin names of allowed runners
149 */
150 void setAllowedRunners(const QStringList &runners);
151
152 /**
153 * Attempts to add the AbstractRunner plugin represented
154 * by the plugin info passed in. Usually one can simply let
155 * the configuration of plugins handle loading Runner plugins,
156 * but in cases where specific runners should be loaded this
157 * allows for that to take place
158 * @note Consider using @ref setAllowedRunners in case you want to only allow specific runners
159 *
160 * @param pluginMetaData the metaData to use to load the plugin
161 * @return the loaded runner or nullptr
162 */
163 AbstractRunner *loadRunner(const KPluginMetaData &pluginMetaData);
164
165 /**
166 * @return mime data of the specified match
167 */
168 QMimeData *mimeDataForMatch(const QueryMatch &match) const;
169
170 /**
171 * @return metadata list of all known Runner plugins
172 * @since 5.72
173 */
174 static QList<KPluginMetaData> runnerMetaDataList();
175
176public Q_SLOTS:
177 /**
178 * Call this method when the runners should be prepared for a query session.
179 * Call matchSessionComplete when the query session is finished for the time
180 * being.
181 * @see matchSessionComplete
182 */
183 void setupMatchSession();
184
185 /**
186 * Call this method when the query session is finished for the time
187 * being.
188 * @see prepareForMatchSession
189 */
190 void matchSessionComplete();
191
192 /**
193 * Launch a query, this will create threads and return immediately.
194 * When the information will be available can be known using the
195 * matchesChanged signal.
196 *
197 * @param term the term we want to find matches for
198 * @param runnerId optional, if only one specific runner is to be used;
199 * providing an id will put the manager into single runner mode
200 */
201 void launchQuery(const QString &term, const QString &runnerId = QString());
202
203 /**
204 * Reset the current data and stops the query
205 */
206 void reset();
207
208Q_SIGNALS:
209 /**
210 * Emitted each time a new match is added to the list
211 */
212 void matchesChanged(const QList<KRunner::QueryMatch> &matches);
213
214 /**
215 * Emitted when the launchQuery finish
216 */
217 void queryFinished();
218
219 /**
220 * Put the given search term in the KRunner search field
221 * @param term The term that should be displayed
222 * @param cursorPosition Where the cursor should be positioned
223 * @since 6.0
224 */
225 void requestUpdateQueryString(const QString &term, int cursorPosition);
226
227 /**
228 * @see @p historyEnabled
229 * @since 5.78
230 */
231 void historyEnabledChanged();
232
233private:
234 // exported for dbusrunnertest
235 KPluginMetaData convertDBusRunnerToJson(const QString &filename) const;
236 KRUNNER_NO_EXPORT Q_INVOKABLE void onMatchesChanged();
237
238 std::unique_ptr<RunnerManagerPrivate> d;
239
240 friend class RunnerManagerPrivate;
241 friend AbstractRunnerTest;
242 friend AbstractRunner;
243};
244
245}
246#endif
247

source code of krunner/src/runnermanager.h