KRunner

abstractrunner.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <[email protected]>
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
19 class KConfigGroup;
20 class 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 
42 class QAction;
43 class QMimeData;
44 class QRegularExpression;
45 
46 namespace Plasma
47 {
48 class DataEngine;
49 class Package;
50 class QueryMatch;
51 class AbstractRunnerPrivate;
52 
53 enum RunnerReturnPluginMetaDataConstant { RunnerReturnPluginMetaData }; // KF6: remove again
54 
55 /**
56  * @class AbstractRunner abstractrunner.h <KRunner/AbstractRunner>
57  *
58  * @short An abstract base class for Plasma Runner plugins.
59  *
60  * Be aware that runners have to be thread-safe. This is due to the fact that
61  * each runner is executed in its own thread for each new term. Thus, a runner
62  * may be executed more than once at the same time. See match() for details.
63  * To let krunner expose a global shortcut for the single runner query mode, the runner
64  * must set the "X-Plasma-AdvertiseSingleRunnerMode" key to true in the .desktop file
65  * and set a default syntax. See setDefaultSyntax() for details.
66  *
67  */
68 class 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 
79 public:
80 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
81  /** Specifies a nominal speed for the runner */
82  enum Speed{
83  SlowSpeed,
84  NormalSpeed,
85  };
86 #endif
87 
88  /** Specifies a priority for the runner */
89  enum Priority {
90  LowestPriority = 0,
91  LowPriority,
92  NormalPriority,
93  HighPriority,
94  HighestPriority,
95  };
96 
97  /** An ordered list of runners */
99 
100  ~AbstractRunner() override;
101 
102  /**
103  * This is the main query method. It should trigger creation of
104  * QueryMatch instances through RunnerContext::addMatch and
105  * RunnerContext::addMatches.
106  *
107  * If the runner can run precisely the requested term (RunnerContext::query()),
108  * it should create an exact match by setting the type to RunnerContext::ExactMatch.
109  * The first runner that creates a QueryMatch will be the
110  * default runner. Other runner's matches will be suggested in the
111  * interface. Non-exact matches should be offered via RunnerContext::PossibleMatch.
112  *
113  * The match will be activated via run() if the user selects it.
114  *
115  * Each runner is executed in its own thread. Whenever the user input changes this
116  * method is called again. Thus, it needs to be thread-safe. Also, all matches need
117  * to be reported once this method returns. Asynchronous runners therefore need
118  * to make use of a local event loop to wait for all matches.
119  *
120  * It is recommended to use local status data in async runners. The simplest way is
121  * to have a separate class doing all the work like so:
122  *
123  * \code
124  * void MyFancyAsyncRunner::match(RunnerContext &context)
125  * {
126  * QEventLoop loop;
127  * MyAsyncWorker worker(context);
128  * connect(&worker, &MyAsyncWorker::finished, &loop, &MyAsyncWorker::quit);
129  * worker.work();
130  * loop.exec();
131  * }
132  * \endcode
133  *
134  * Here MyAsyncWorker creates all the matches and calls RunnerContext::addMatch
135  * in some internal slot. It emits the finished() signal once done which will
136  * quit the loop and make the match() method return. The local status is kept
137  * entirely in MyAsyncWorker which makes match() trivially thread-safe.
138  *
139  * If a particular match supports multiple actions, set up the corresponding
140  * actions in the actionsForMatch method. Do not call any of the action methods
141  * within this method!
142  *
143  * Execution of the correct action should be handled in the run method.
144  * @caution This method needs to be thread-safe since KRunner will simply
145  * start a new thread for each new term.
146  *
147  * @warning Returning from this method means to end execution of the runner.
148  *
149  * @sa run(), RunnerContext::addMatch, RunnerContext::addMatches, QueryMatch
150  */
151  virtual void match(Plasma::RunnerContext &context);
152 
153 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
154  /**
155  * Triggers a call to match. This will call match() internally.
156  *
157  * @param context the search context used in executing this match.
158  * @deprecated Since 5.81, use match(Plasma::RunnerContext &context) instead.
159  * This method contains logic to delay slow runners, which is now deprecated. Consequently you
160  * should call match(Plasma::RunnerContext &context) directly.
161  */
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)
167  /**
168  * If the runner has options that the user can interact with to modify
169  * what happens when run or one of the actions created in match
170  * is called, the runner should return true
171  * @deprecated Since 5.0, this feature has been defunct
172  */
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)
178  /**
179  * If hasRunOptions() returns true, this method may be called to get
180  * a widget displaying the options the user can interact with to modify
181  * the behaviour of what happens when a given match is selected.
182  *
183  * @param widget the parent of the options widgets.
184  * @deprecated Since 5.0, this feature has been defunct
185  */
186  KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
187  virtual void createRunOptions(QWidget *widget);
188 #endif
189 
190  /**
191  * Called whenever an exact or possible match associated with this
192  * runner is triggered.
193  *
194  * @param context The context in which the match is triggered, i.e. for which
195  * the match was created.
196  * @param match The actual match to run/execute.
197  */
198  virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match);
199 
200 #if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
201  /**
202  * Return a list of categories that this runner provides. By default
203  * this list just contains the runners name. It is used by the runner manager
204  * to disable certain runners if all the categories they provide have
205  * been disabled.
206  *
207  * This list of categories is also used to provide a better way to
208  * configure the runner instead of the typical on / off switch.
209  * @deprecated Since 5.76, feature is unused. You can still set the category property in the QueryMatch
210  */
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)
216  /**
217  * Returns the icon which accurately describes the category \p category.
218  * This is meant to be used in a configuration dialog when showing
219  * all the categories.
220  *
221  * By default this returns the icon of the AbstractRunner
222  * * @deprecated Since 5.0, feature removed
223  */
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)
229  /**
230  * The nominal speed of the runner.
231  * @see setSpeed
232  */
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 
237  /**
238  * The priority of the runner.
239  * @see setPriority
240  */
241  Priority priority() const;
242 
243 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
244  /**
245  * Returns the OR'ed value of all the Information types (as defined in RunnerContext::Type)
246  * this runner is not interested in.
247  * @return OR'ed value of black listed types
248  * @deprecated This feature is deprecated
249  */
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)
255  /**
256  * Sets the types this runner will ignore. If the value from RunnerContext::type() is contained in the ignored types
257  * the match() method won't be called. This way there is no unnecessary thread spawned. The same RunnerContext from
258  * which the type gets read is later passed into the match(Plasma::RunnerContext &context) method call.
259  * @param types OR'ed listed of ignored types
260  * @deprecated feature is deprecated. Consider using the minLetterCount and matchRegex properties instead. These
261  * properties also prevent thread spawning, but can be used far more precise.
262  * If you want to have this kind of optimization for older KRunner versions you could wrap this
263  * inside of an version if statement:
264  * @code
265  #if KRUNNER_VERSION < QT_VERSION_CHECK(5, 76, 0)
266  //set ignore types
267  #endif
268  * @endcode
269  * The minLetterCount and matchRegex can be set with a similar version check or added to the desktop file.
270  * If an older KRunner version loads such a desktop file these unknown properties are just ignored.
271  * @see minLetterCount
272  * @see matchRegex
273  */
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 
278  /**
279  * @return the user visible engine name for the Runner
280  */
281  QString name() const;
282 
283  /**
284  * @return an id string for the Runner
285  */
286  QString id() const;
287 
288  /**
289  * @return the description of this Runner
290  */
291  QString description() const;
292 
293 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
294  /**
295  * @return the plugin info for this runner
296  * @deprecated since 5.72, use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs
297  */
298  KRUNNER_DEPRECATED_VERSION(5, 72, "Use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs")
299  KPluginInfo metadata() const;
300 #endif
301 
302  /**
303  * @return the plugin metadata for this runner
304  *
305  * Overload to get non-deprecated metadata format. Use like this:
306  * @code
307  * KPluginMetaData md = runner->metadata(Plasma::RunnerReturnPluginMetaData);
308  * @endcode
309  * If you disable the deprecated version using the KRUNNER_DISABLE_DEPRECATED_BEFORE_AND_AT macro,
310  * then you can omit Plasma::RunnerReturnPluginMetaDataConstant and use it like this:
311  * @code
312  * KPluginMetaData md = runner->metadata();
313  * @endcode
314  *
315  * @since 5.72
316  */
317 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
318  KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant) const;
319 #else
320  KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant = RunnerReturnPluginMetaData) const;
321 #endif
322  /**
323  * @return the icon for this Runner
324  */
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
329  /**
330  * Accessor for the associated Package object if any.
331  *
332  * Note that the returned pointer is only valid for the lifetime of
333  * the runner.
334  *
335  * @return the Package object, which may be invalid
336  * @deprecated since 5.28, use KPackage::Package instead, no accessor in this class
337  **/
338  KRUNNER_DEPRECATED_VERSION(5, 28, "No longer use, feature removed")
339  Package package() const;
340 #endif
341 #endif
342 
343  /**
344  * Signal runner to reload its configuration.
345  */
346  virtual void reloadConfiguration();
347 
348  /**
349  * @return the syntaxes the runner has registered that it accepts and understands
350  * @since 4.3
351  */
352  QList<RunnerSyntax> syntaxes() const;
353 
354 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
355  /**
356  * @return the default syntax for the runner or @c nullptr if no default syntax has been defined
357  *
358  * @since 4.4
359  * @deprecated Since 5.76, feature is unused.
360  */
361  KRUNNER_DEPRECATED_VERSION(5, 76, "No longer use, feature is unused")
362  RunnerSyntax *defaultSyntax() const;
363 #endif
364 
365  /**
366  * @return true if the runner is currently busy with non-interuptable work, signaling that
367  * new threads should not be created for it at this time
368  * @since 4.6
369  */
370  bool isMatchingSuspended() const;
371 
372  /**
373  * This is the minimum letter count for the query. If the query is shorter than this value
374  * and KRunner is not in the singleRunnerMode, the performMatch and consequently match method is not called.
375  * This can be set using the X-Plasma-Runner-Min-Letter-Count property or the setMinLetterCount method.
376  * @see setMinLetterCount
377  * @see match
378  * @see performMatch
379  * @return minLetterCount property
380  * @since 5.75
381  */
382  int minLetterCount() const;
383 
384  /**
385  * Set the minLetterCount property
386  * @param count
387  * @since 5.75
388  */
389  void setMinLetterCount(int count);
390 
391  /**
392  * If this regex is set with a not empty pattern it must match the query in
393  * order for the performMatch/match being called.
394  * Just like the minLetterCount property this check is ignored when the runner is in the singleRunnerMode.
395  * In case both the regex and the letter count is set the letter count is checked first.
396  * @return matchRegex property
397  * @see hasMatchRegex
398  * @since 5.75
399  */
400  QRegularExpression matchRegex() const;
401 
402  /**
403  * Set the matchRegex property
404  * @param regex
405  * @since 5.75
406  */
407  void setMatchRegex(const QRegularExpression &regex);
408 
409  /**
410  * Constructs internally a regex which requires the query to start with the trigger words.
411  * Multiple words are concatenated with or, for instance: "^word1|word2|word3".
412  * The trigger words are internally escaped.
413  * Also the minLetterCount is set to the shortest word in the list.
414  * @since 5.75
415  * @see matchRegex
416  */
417  void setTriggerWords(const QStringList &triggerWords);
418 
419  /**
420  * If the runner has a valid regex and non empty regex
421  * @return hasMatchRegex
422  * @since 5.75
423  */
424  bool hasMatchRegex() const;
425 
426 Q_SIGNALS:
427  /**
428  * This signal is emitted when matching is about to commence, giving runners
429  * an opportunity to prepare themselves, e.g. loading data sets or preparing
430  * IPC or network connections. This method should be fast so as not to cause
431  * slow downs. Things that take longer or which should be loaded once and
432  * remain extant for the lifespan of the AbstractRunner should be done in init().
433  * @see init()
434  * @since 4.4
435  */
436  void prepare();
437 
438  /**
439  * This signal is emitted when a session of matches is complete, giving runners
440  * the opportunity to tear down anything set up as a result of the prepare()
441  * method.
442  * @since 4.4
443  */
444  void teardown();
445 
446  /**
447  * Emitted when the runner enters or exits match suspension
448  * @see matchingSuspended
449  * @since 4.6
450  */
451  void matchingSuspended(bool suspended);
452 
453 protected:
454  friend class RunnerManager;
455  friend class RunnerManagerPrivate;
456 
457  /**
458  * Constructor for a KRunner plugin
459  * @param parent parent object for this runner
460  * @param pluginMetaData metadata that was embedded in the runner
461  * @param args for compatibility with KPluginFactory, should be passed on to the parent constructor
462  * @since 5.72
463  */
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)
475  /// @deprecated Since 5.72, use AbstractRunner(const KPluginMetaData &, QObject *)
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)
481  /// @since 5.72
482  explicit AbstractRunner(const KPluginMetaData &pluginMetaData, QObject *parent = nullptr);
483 #endif
484 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
485  /// @deprecated Since 5.77, use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)
486  KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
487  AbstractRunner(QObject *parent, const QVariantList &args);
488 #endif
489 
490  /**
491  * Sets whether or not the runner is available for match requests. Useful to
492  * prevent more thread spawning when the thread is in a busy state.
493  */
494  void suspendMatching(bool suspend);
495 
496  /**
497  * Provides access to the runner's configuration object.
498  */
499  KConfigGroup config() const;
500 
501 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
502  /**
503  * Sets whether or not the runner has options for matches
504  * @deprecated Since 5.0, this feature has been defunct
505  */
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)
511  /**
512  * Sets the nominal speed of the runner. Only slow runners need
513  * to call this within their constructor because the default
514  * speed is NormalSpeed. Runners that use D-Bus should call
515  * this within their constructors.
516  * @deprecated Since 5.81, the concept of delayed runners is deprecated.
517  * If you have resource or memory intensive tasks consider porting the runner to a D-Bus runner.
518  * Otherwise you can set the priority of the runner to LowPriority and implement the wait using a QTimer and an
519  * event loop. It is important to check if the RunnerContext is still valid after the waiting interval.
520  */
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 
525  /**
526  * Sets the priority of the runner. Lower priority runners are executed
527  * only after higher priority runners.
528  */
529  void setPriority(Priority newPriority);
530 
531  /**
532  * A given match can have more than action that can be performed on it.
533  * For example, a song match returned by a music player runner can be queued,
534  * added to the playlist, or played.
535  *
536  * Call this method to add actions that can be performed by the runner.
537  * Actions must first be added to the runner's action registry.
538  * Note: execution of correct action is left up to the runner.
539  */
540  virtual QList<QAction *> actionsForMatch(const Plasma::QueryMatch &match);
541 
542 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
543  /**
544  * Creates and then adds an action to the action registry.
545  * AbstractRunner assumes ownership of the created action.
546  *
547  * @see QueryMatch::setActions
548  * @see actionsForMatch
549  *
550  * @param id A unique identifier string
551  * @param icon The icon to display
552  * @param text The text to display
553  * @return the created QAction
554  * @deprecated Since 5.86 create the QAction instance manually
555  * @code
556  * // in the runner class definition
557  * QList<QAction *> m_actions;
558  * // when initializing the runner, optionally set the date if needed
559  * auto action = new QAction(QIcon::fromTheme(iconName), text, this);
560  * m_actions << action;
561  * // when creating the match
562  * match.setActions(m_actions);
563  * @endcode
564  */
565  KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
566  QAction *addAction(const QString &id, const QIcon &icon, const QString &text);
567 
568  /**
569  * Adds an action to the runner's action registry.
570  *
571  * The QAction must be created within the GUI thread;
572  * do not create it within the match method of AbstractRunner.
573  *
574  * @param id A unique identifier string
575  * @param action The QAction to be stored
576  * @deprecated Since 5.86, create the QAction instance manually
577  */
578  KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
579  void addAction(const QString &id, QAction *action);
580 
581  /**
582  * Removes the action from the action registry.
583  * AbstractRunner deletes the action once removed.
584  *
585  * @param id The id of the action to be removed
586  * @deprecated Since 5.86, deprecated for lack of usage
587  */
588  KRUNNER_DEPRECATED_VERSION(5, 86, "deprecated for lack of usage")
589  void removeAction(const QString &id);
590 
591  /**
592  * Returns the action associated with the id
593  * @deprecated Since 5.86, create the QAction instances manually and store them in a custom container instead
594  */
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 
598  /**
599  * Returns all registered actions
600  * @deprecated Since 5.86, create the QAction instances manually and store them in a custom container instead
601  */
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 
605  /**
606  * Clears the action registry.
607  * The action pool deletes the actions.
608  * @deprecated Since 5.86, use a custom container to store the QAction instances instead
609  */
610  KRUNNER_DEPRECATED_VERSION(5, 86, "use a custom container to store the QAction instances instead")
611  void clearActions();
612 #endif
613 
614  /**
615  * Adds a registered syntax that this runner understands. This is used to
616  * display to the user what this runner can understand and how it can be
617  * used.
618  *
619  * @param syntax the syntax to register
620  * @since 4.3
621  */
622  void addSyntax(const RunnerSyntax &syntax);
623 
624 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
625  /**
626  * Set @p syntax as the default syntax for the runner; the default syntax will be
627  * substituted to the empty query in single runner mode. This is also used to
628  * display to the user what this runner can understand and how it can be
629  * used.
630  * The default syntax is automatically added to the list of registered syntaxes, there
631  * is no need to add it using addSyntax.
632  * Note that there can be only one default syntax; if called more than once, the last
633  * call will determine the default syntax.
634  * A default syntax (even trivial) is required to advertise single runner mode
635  *
636  * @param syntax the syntax to register and to set as default
637  * @since 4.4
638  * @deprecated Since 5.76, feature is unused. Use addSyntax() instead.
639  **/
640  KRUNNER_DEPRECATED_VERSION(5, 76, "Feature unused, use addSyntax() instead")
641  void setDefaultSyntax(const RunnerSyntax &syntax);
642 #endif
643 
644  /**
645  * Utility overload for creating a syntax based on the given parameters
646  * @see RunnerSyntax
647  * @since 5.106
648  */
649  inline void addSyntax(const QString &exampleQuery, const QString &description)
650  {
651  addSyntax(QStringList(exampleQuery), description);
652  }
653 
654  /// @copydoc addSyntax(const QString &exampleQuery, const QString &description)
655  inline void addSyntax(const QStringList &exampleQueries, const QString &description)
656  {
657  addSyntax(RunnerSyntax(exampleQueries, description));
658  }
659 
660  /**
661  * Sets the list of syntaxes; passing in an empty list effectively clears
662  * the syntaxes.
663  *
664  * @param the syntaxes to register for this runner
665  * @since 4.3
666  */
667  void setSyntaxes(const QList<RunnerSyntax> &syns);
668 
669 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 73)
670  /**
671  * Loads the given DataEngine
672  *
673  * Tries to load the data engine given by @p name. Each engine is
674  * only loaded once, and that instance is re-used on all subsequent
675  * requests.
676  *
677  * If the data engine was not found, an invalid data engine is returned
678  * (see DataEngine::isValid()).
679  *
680  * Note that you should <em>not</em> delete the returned engine.
681  *
682  * @param name Name of the data engine to load
683  * @return pointer to the data engine if it was loaded,
684  * or an invalid data engine if the requested engine
685  * could not be loaded
686  *
687  * @since 4.4
688  * @deprecated Since 5.73, DataEngines are deprecated, use e.g. a shared library to provide the data instead.
689  */
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 
694  /**
695  * Reimplement this slot to run any initialization routines on first load.
696  * By default, it calls reloadConfiguration(); for scripted Runners this
697  * method also sets up the ScriptEngine.
698  */
699  virtual void init();
700 
701  /**
702  * Reimplement this slot if you want your runner
703  * to support serialization and drag and drop
704  * @since 4.5
705  */
706  virtual QMimeData *mimeDataForMatch(const Plasma::QueryMatch &match);
707 
708 private:
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
732 /**
733  * @relates Plasma::AbstractRunner
734  *
735  * Registers a runner plugin.
736  *
737  * @deprecated Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead
738  */
739 #define K_EXPORT_PLASMA_RUNNER( libname, classname ) \
740 K_EXPORT_PLASMA_RUNNER_WARNING("Deprecated. Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead") \
741 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
742 #endif
743 
744 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 88)
745 /**
746  * @relates Plasma::AbstractRunner
747  *
748  * Registers a runner plugin with JSON metadata.
749  *
750  * @param classname name of the AbstractRunner derived class.
751  * @param jsonFile name of the JSON file to be compiled into the plugin as metadata
752  *
753  * @since 5.72
754  * @deprecated Since 5.88 use K_PLUGIN_CLASS_WITH_JSON instead
755  */
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)
761 /**
762  * These plugins are Used by the plugin selector dialog to show
763  * configuration options specific to this runner. These options
764  * must be runner global and not pertain to a specific match.
765  * @deprecated Since 5.0, use K_PLUGIN_FACTORY directly
766  */
767 #define K_EXPORT_RUNNER_CONFIG( name, classname ) \
768 K_PLUGIN_FACTORY(ConfigFactory, registerPlugin<classname>();)
769 #endif
770 // clang-format on
771 
772 #if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
773 namespace KRunner
774 {
777 }
778 #endif
779 
780 #endif
The RunnerManager class decides what installed runners are runnable, and their ratings....
Definition: runnermanager.h:46
void addSyntax(const QString &exampleQuery, const QString &description)
Utility overload for creating a syntax based on the given parameters.
Priority
Specifies a priority for the runner.
A match returned by an AbstractRunner in response to a given RunnerContext.
Definition: querymatch.h:34
An abstract base class for Plasma Runner plugins.
void addSyntax(const QStringList &exampleQueries, const QString &description)
Utility overload for creating a syntax based on the given parameters.
void suspend()
KSharedConfigPtr config()
Speed
Specifies a nominal speed for the runner.
QList< AbstractRunner * > List
An ordered list of runners.
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:50:59 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.