KRunner

runnermanager.h
1 /*
2  SPDX-FileCopyrightText: 2006 Aaron Seigo <[email protected]>
3  SPDX-FileCopyrightText: 2007 Ryan P. Bitanga <[email protected]>
4  SPDX-FileCopyrightText: 2008 Jordi Polo <[email protected]>
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 
26 class QAction;
27 class KConfigGroup;
28 namespace
29 {
30 class AbstractRunnerTest;
31 }
32 
33 namespace Plasma
34 {
35 class QueryMatch;
36 class AbstractRunner;
37 class RunnerContext;
38 class RunnerManagerPrivate;
39 
40 /**
41  * @class RunnerManager runnermanager.h <KRunner/RunnerManager>
42  *
43  * @short The RunnerManager class decides what installed runners are runnable,
44  * and their ratings. It is the main proxy to the runners.
45  */
46 class 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 
54 public:
55  explicit RunnerManager(QObject *parent = nullptr);
56  explicit RunnerManager(const QString &configFile, QObject *parent = nullptr);
57 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
58  /**
59  * @deprecated Since 5.76, use "RunnerManager(const QString &configFile, QObject *parent)" instead.
60  */
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 
66  /**
67  * Finds and returns a loaded runner or NULL
68  * @param pluginName the name of the runner plugin
69  * @return Pointer to the runner
70  */
71  AbstractRunner *runner(const QString &pluginName) const;
72 
73 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 82)
74  /**
75  * @return the currently active "single mode" runner, or null if none
76  * @since 4.4
77  * @deprecated Since 5.81, the dedicated singleRunnerMode methods are deprecated, use runner(const QString &pluginName) with the singleRunnerId instead"
78  */
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 
84  /**
85  * Puts the manager into "single runner" mode using the given
86  * runner; if the runner does not exist or can not be loaded then
87  * the single runner mode will not be started and singleModeRunner()
88  * will return NULL
89  * @param id the id of the runner to use
90  * @since 4.4
91  * @deprecated Since 5.82, the dedicated singleRunnerMode methods are deprecated, pass in the singleModeRunnerId into the launchQuery overload instead
92  */
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 
98  /**
99  * @return the id of the runner to use in single mode
100  * @since 4.4
101  * @deprecated Since 5.82, the dedicated singleRunnerMode methods are deprecated, use runner(const QString &pluginName) with the singleRunnerId instead
102  */
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 
106  /**
107  * @return true if the manager is set to run in single runner mode
108  * @since 4.4
109  * @deprecated Since 5.82, the dedicated singleRunnerMode methods are deprecated, call the RunnerContext::singleRunnerQueryMode on the searchContext instead
110  */
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 
117  /**
118  * Sets whether or not the manager is in single mode.
119  *
120  * @param singleMode true if the manager should be in single mode, false otherwise
121  * @since 4.4
122  * @deprecated Since 5.82, the dedicated singleRunnerMode methods are deprecated, the single mode is set to true when launchQuery is called with a non
123  * empty and existing runnerId
124  */
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 
131  /**
132  * @return the names of all runners that advertise single query mode
133  * @since 4.4
134  * @deprecated Since 5.81, filter the runners manually using the X-Plasma-AdvertiseSingleRunnerQueryMode of the metadata
135  */
136  KRUNNER_DEPRECATED_VERSION(5, 81, "filter the runners manually using the X-Plasma-AdvertiseSingleRunnerQueryMode of the metadata")
137  QStringList singleModeAdvertisedRunnerIds() const;
138 
139  /**
140  * Returns the translated name of a runner
141  * @param id the id of the runner
142  *
143  * @since 4.4
144  * @deprecated Since 5.81, call runner(const QString &id) and fetch the name from the returned object instead
145  */
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 
150  /**
151  * @return the list of all currently loaded runners
152  */
153  QList<AbstractRunner *> runners() const;
154 
155  /**
156  * Retrieves the current context
157  * @return pointer to the current context
158  */
159  RunnerContext *searchContext() const;
160 
161  /**
162  * Retrieves all available matches found so far for the previously launched query
163  * @return List of matches
164  */
165  QList<QueryMatch> matches() const;
166 
167  /**
168  * Runs a given match
169  * @param match the match to be executed
170  */
171  void run(const QueryMatch &match);
172 
173 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 79)
174  /**
175  * Runs a given match
176  * @param id the id of the match to run
177  * @deprecated Since 5.79, use run(const QueryMatch &match) instead
178  */
179  KRUNNER_DEPRECATED_VERSION(5, 79, "Use run(const QueryMatch &match) instead")
180  void run(const QString &id);
181 #endif
182 
183  /**
184  * Runs a given match. This also respects the extra handling for the InformationalMatch.
185  * This also handles the history automatically
186  * @param match the match to be executed
187  * @return if the RunnerWindow should close
188  * @since 5.78
189  */
190  bool runMatch(const QueryMatch &match);
191 
192  /**
193  * Retrieves the list of actions, if any, for a match
194  */
195  QList<QAction *> actionsForMatch(const QueryMatch &match);
196 
197  /**
198  * @return the current query term
199  */
200  QString query() const;
201 
202  /**
203  * @return History of this runner for the current activity. If the RunnerManager is not history
204  * aware the global entries will be returned.
205  * @since 5.78
206  */
207  QStringList history() const;
208 
209  /**
210  * Delete the given index from the history.
211  * @param historyEntry
212  * @since 5.78
213  */
214  Q_INVOKABLE void removeFromHistory(int index);
215 
216  /**
217  * Get the suggested history entry for the typed query. If no entry is found an empty string is returned.
218  * @param typedQuery
219  * @return completion for typedQuery
220  * @since 5.78
221  */
222  Q_INVOKABLE QString getHistorySuggestion(const QString &typedQuery) const;
223 
224  /**
225  * Get the suggested prior search for this runner.
226  * Just like the history this value can be activity specific, depending on the build/config.
227  * @return priorSearch
228  * @since 5.78
229  */
230  QString priorSearch() const;
231 
232  /**
233  * Set the prior search for this runner. Setting an empty string will clear this value.
234  * @since 5.78
235  */
236  void setPriorSearch(const QString &search);
237 
238  /**
239  * If the prior search should be restored when KRunner is reopened
240  * @since 5.78
241  */
242  bool retainPriorSearch();
243 
244  /**
245  * If history completion is enabled, the default value is true.
246  * @since 5.78
247  */
248  bool historyEnabled();
249 
250  /**
251  * Causes a reload of the current configuration
252  */
253  void reloadConfiguration();
254 
255  /**
256  * Sets a whitelist for the plugins that can be loaded by this manager.
257  *
258  * @param plugins the plugin names of allowed runners
259  * @since 4.4
260  */
261  void setAllowedRunners(const QStringList &runners);
262 
263 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
264  /**
265  * Sets the list of categories which matches should be
266  * returned for. It also internally tries not to execute the
267  * runners which do not fall in this category.
268  * @deprecated Since 5.76, feature is unused and not supported by most runners
269  */
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)
276  /**
277  * Attempts to add the AbstractRunner plugin represented
278  * by the KService passed in. Usually one can simply let
279  * the configuration of plugins handle loading Runner plugins,
280  * but in cases where specific runners should be loaded this
281  * allows for that to take place
282  *
283  * @param service the service to use to load the plugin
284  * @since 4.5
285  * @deprecated Since 5.72, use loadRunner(const KPluginMetaData &)
286  */
287  KRUNNER_DEPRECATED_VERSION(5, 72, "use loadRunner(const KPluginMetaData &)")
288  void loadRunner(const KService::Ptr service);
289 #endif
290 #endif
291 
292  /**
293  * Attempts to add the AbstractRunner plugin represented
294  * by the plugin info passed in. Usually one can simply let
295  * the configuration of plugins handle loading Runner plugins,
296  * but in cases where specific runners should be loaded this
297  * allows for that to take place
298  *
299  * @param pluginMetaData the metaData to use to load the plugin
300  * @since 5.72
301  */
302  void loadRunner(const KPluginMetaData &pluginMetaData);
303 
304 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
305  /**
306  * Attempts to add the AbstractRunner from a Plasma::Package on disk.
307  * Usually one can simply let the configuration of plugins
308  * handle loading Runner plugins, but in cases where specific
309  * runners should be loaded this allows for that to take place
310  *
311  * @param path the path to a Runner package to load
312  * @since 4.5
313  * @deprecated Since 5.0, the KPackage support was removed in Plasma 5.0
314  */
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)
320  /**
321  * @return the list of allowed plugins
322  * @since 4.4
323  * @deprecated Since 5.88, reading allowed runners from the config is deprecated, use @p runners() and get their @p AbstractRunner::id instead
324  */
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)
330  /**
331  * @return the list of enabled categories
332  * @deprecated Since 5.76, feature is unused and not supported by most runners
333  */
334  KRUNNER_DEPRECATED_VERSION(5, 76, "feature is unused and not supported by most runners")
335  QStringList enabledCategories() const;
336 #endif
337 
338  /**
339  * @return mime data of the specified match
340  * @since 4.5
341  */
342  QMimeData *mimeDataForMatch(const QueryMatch &match) const;
343 
344 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 79)
345  /**
346  * @return mime data of the specified match
347  * @since 4.5
348  * @deprecated Since 5.79, use mimeDataForMatch(const QueryMatch &match) instead
349  */
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)
355  /**
356  * Returns a list of all known Runner implementations
357  *
358  * @param parentApp the application to filter runners on. Uses the
359  * X-KDE-ParentApp entry (if any) in the plugin metadata.
360  * The default value of QString() will result in a
361  * list containing only runners not specifically
362  * registered to an application.
363  * @return list of metadata of known runners
364  * @since 5.72
365  * @deprecated Since 5.85, the concept of parent apps for runners is deprecated, use no-arg overload instead
366  **/
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 
371  /**
372  * @return metadata list of all known Runner implementations
373  * @since 5.72
374  */
375  static QVector<KPluginMetaData> runnerMetaDataList();
376 
377 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
378  /**
379  * Returns a list of all known Runner implementations
380  *
381  * @param parentApp the application to filter applets on. Uses the
382  * X-KDE-ParentApp entry (if any) in the plugin info.
383  * The default value of QString() will result in a
384  * list containing only applets not specifically
385  * registered to an application.
386  * @return list of AbstractRunners
387  * @since 4.6
388  * @deprecated since 5.72, use runnerMetaDataList() instead
389  **/
390  KRUNNER_DEPRECATED_VERSION(5, 72, "Use runnerMetaDataList() instead")
391  static KPluginInfo::List listRunnerInfo(const QString &parentApp = QString());
392 #endif
393 
394  /**
395  * If you call this method the manager will create a KConfigWatcher
396  * which reload its runners or the runner configuration when the settings in the KCM are edited.
397  * @since 5.73
398  * @see reloadConfiguration
399  */
400  void enableKNotifyPluginWatcher(); // TODO KF6 make enabling the watcher default behavior and remove the method
401 
402 public Q_SLOTS:
403  /**
404  * Call this method when the runners should be prepared for a query session.
405  * Call matchSessionComplete when the query session is finished for the time
406  * being.
407  * @since 4.4
408  * @see matchSessionComplete
409  */
410  void setupMatchSession();
411 
412  /**
413  * Call this method when the query session is finished for the time
414  * being.
415  * @since 4.4
416  * @see prepareForMatchSession
417  */
418  void matchSessionComplete();
419 
420  /**
421  * Launch a query, this will create threads and return immediately.
422  * When the information will be available can be known using the
423  * matchesChanged signal.
424  *
425  * @param term the term we want to find matches for
426  * @param runnerId optional, if only one specific runner is to be used;
427  * providing an id will put the manager into single runner mode
428  */
429  void launchQuery(const QString &term, const QString &runnerId);
430 
431  /**
432  * Convenience version of above
433  */
434  void launchQuery(const QString &term); // TODO KF6 Merge with other overload and use default argument
435 
436  /**
437  * Reset the current data and stops the query
438  */
439  void reset();
440 
441 Q_SIGNALS:
442  /**
443  * Emitted each time a new match is added to the list
444  */
445  void matchesChanged(const QList<Plasma::QueryMatch> &matches);
446 
447  /**
448  * Emitted when the launchQuery finish
449  * @since 4.5
450  */
451  void queryFinished();
452 
453  /**
454  * Put the given search term in the KRunner search field
455  * @param term The term that should be displayed
456  * @param cursorPosition Where the cursor should be positioned
457  * @since 5.78
458  */
459  void setSearchTerm(const QString &term, int cursorPosition);
460 
461  /**
462  * @see @p historyEnabled
463  * @since 5.78
464  */
465  void historyEnabledChanged();
466 
467 private:
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)
480 namespace KRunner
481 {
482 using RunnerManager = Plasma::RunnerManager;
483 }
484 #endif
485 
486 #endif
The RunnerManager class decides what installed runners are runnable, and their ratings....
Definition: runnermanager.h:46
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition: querymatch.h:34
An abstract base class for Plasma Runner plugins.
KSharedConfigPtr config()
The RunnerContext class provides information related to a search, including the search term,...
Definition: runnercontext.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.