KRunner

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 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, const 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 */
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
208 /**
209 * Set the environment identifier for recording history and launch counts
210 * @internal
211 * @since 6.0
212 */
213 Q_INVOKABLE void setHistoryEnvironmentIdentifier(const QString &identifier);
214
215Q_SIGNALS:
216 /**
217 * Emitted each time a new match is added to the list
218 */
220
221 /**
222 * Emitted when the launchQuery finish
223 */
225
226 /**
227 * Put the given search term in the KRunner search field
228 * @param term The term that should be displayed
229 * @param cursorPosition Where the cursor should be positioned
230 * @since 6.0
231 */
232 void requestUpdateQueryString(const QString &term, int cursorPosition);
233
234 /**
235 * @see @p historyEnabled
236 * @since 5.78
237 */
239
240private:
241 // exported for dbusrunnertest
242 KPluginMetaData convertDBusRunnerToJson(const QString &filename) const;
243 KRUNNER_NO_EXPORT Q_INVOKABLE void onMatchesChanged();
244
245 std::unique_ptr<RunnerManagerPrivate> d;
246
247 friend class RunnerManagerPrivate;
248 friend AbstractRunnerTest;
249 friend AbstractRunner;
250};
251
252}
253#endif
This class provides a basic structure for a runner test.
An abstract base class for Plasma Runner plugins.
This class represents an action that will be shown next to a match.
Definition action.h:23
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition querymatch.h:32
The RunnerContext class provides information related to a search, including the search term and colle...
The RunnerManager class decides what installed runners are runnable, and their ratings.
bool historyEnabled()
If history completion is enabled, the default value is true.
void matchesChanged(const QList< KRunner::QueryMatch > &matches)
Emitted each time a new match is added to the list.
void requestUpdateQueryString(const QString &term, int cursorPosition)
Put the given search term in the KRunner search field.
void queryFinished()
Emitted when the launchQuery finish.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 12:01:02 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.