File indexing completed on 2024-04-28 11:44:18
0001 /* 0002 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef PLASMA_ABSTRACTRUNNER_H 0008 #define PLASMA_ABSTRACTRUNNER_H 0009 0010 #include "krunner_export.h" 0011 0012 #include <QObject> 0013 #include <QStringList> 0014 0015 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 94) 0016 #include <KConfigGroup> 0017 #include <QIcon> 0018 #else 0019 class KConfigGroup; 0020 class QIcon; 0021 #endif 0022 #include <KPluginMetaData> 0023 0024 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91) 0025 #include <KPluginInfo> 0026 #include <KService> 0027 #else 0028 #include <KPluginFactory> 0029 #endif 0030 0031 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65) 0032 #include <plasma/plasma_export.h> // for PLASMA_ENABLE_DEPRECATED_SINCE 0033 #include <plasma_version.h> 0034 #endif 0035 0036 #include <memory> 0037 0038 #include "querymatch.h" 0039 #include "runnercontext.h" 0040 #include "runnersyntax.h" 0041 0042 class QAction; 0043 class QMimeData; 0044 class QRegularExpression; 0045 0046 namespace Plasma 0047 { 0048 class DataEngine; 0049 class Package; 0050 class QueryMatch; 0051 class AbstractRunnerPrivate; 0052 0053 enum RunnerReturnPluginMetaDataConstant { RunnerReturnPluginMetaData }; // KF6: remove again 0054 0055 /** 0056 * @class AbstractRunner abstractrunner.h <KRunner/AbstractRunner> 0057 * 0058 * @short An abstract base class for Plasma Runner plugins. 0059 * 0060 * Be aware that runners have to be thread-safe. This is due to the fact that 0061 * each runner is executed in its own thread for each new term. Thus, a runner 0062 * may be executed more than once at the same time. See match() for details. 0063 * To let krunner expose a global shortcut for the single runner query mode, the runner 0064 * must set the "X-Plasma-AdvertiseSingleRunnerMode" key to true in the .desktop file 0065 * and set a default syntax. See setDefaultSyntax() for details. 0066 * 0067 */ 0068 class KRUNNER_EXPORT AbstractRunner : public QObject 0069 { 0070 Q_OBJECT 0071 Q_PROPERTY(bool matchingSuspended READ isMatchingSuspended WRITE suspendMatching NOTIFY matchingSuspended) 0072 Q_PROPERTY(QString id READ id) 0073 Q_PROPERTY(QString description READ description) 0074 Q_PROPERTY(QString name READ name) 0075 Q_PROPERTY(QIcon icon READ icon) 0076 Q_PROPERTY(int minLetterCount READ minLetterCount WRITE setMinLetterCount) 0077 Q_PROPERTY(QRegularExpression matchRegex READ matchRegex WRITE setMatchRegex) 0078 0079 public: 0080 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81) 0081 /** Specifies a nominal speed for the runner */ 0082 enum Speed{ 0083 SlowSpeed, 0084 NormalSpeed, 0085 }; 0086 #endif 0087 0088 /** Specifies a priority for the runner */ 0089 enum Priority { 0090 LowestPriority = 0, 0091 LowPriority, 0092 NormalPriority, 0093 HighPriority, 0094 HighestPriority, 0095 }; 0096 0097 /** An ordered list of runners */ 0098 typedef QList<AbstractRunner *> List; 0099 0100 ~AbstractRunner() override; 0101 0102 /** 0103 * This is the main query method. It should trigger creation of 0104 * QueryMatch instances through RunnerContext::addMatch and 0105 * RunnerContext::addMatches. 0106 * 0107 * If the runner can run precisely the requested term (RunnerContext::query()), 0108 * it should create an exact match by setting the type to RunnerContext::ExactMatch. 0109 * The first runner that creates a QueryMatch will be the 0110 * default runner. Other runner's matches will be suggested in the 0111 * interface. Non-exact matches should be offered via RunnerContext::PossibleMatch. 0112 * 0113 * The match will be activated via run() if the user selects it. 0114 * 0115 * Each runner is executed in its own thread. Whenever the user input changes this 0116 * method is called again. Thus, it needs to be thread-safe. Also, all matches need 0117 * to be reported once this method returns. Asynchronous runners therefore need 0118 * to make use of a local event loop to wait for all matches. 0119 * 0120 * It is recommended to use local status data in async runners. The simplest way is 0121 * to have a separate class doing all the work like so: 0122 * 0123 * \code 0124 * void MyFancyAsyncRunner::match(RunnerContext &context) 0125 * { 0126 * QEventLoop loop; 0127 * MyAsyncWorker worker(context); 0128 * connect(&worker, &MyAsyncWorker::finished, &loop, &MyAsyncWorker::quit); 0129 * worker.work(); 0130 * loop.exec(); 0131 * } 0132 * \endcode 0133 * 0134 * Here MyAsyncWorker creates all the matches and calls RunnerContext::addMatch 0135 * in some internal slot. It emits the finished() signal once done which will 0136 * quit the loop and make the match() method return. The local status is kept 0137 * entirely in MyAsyncWorker which makes match() trivially thread-safe. 0138 * 0139 * If a particular match supports multiple actions, set up the corresponding 0140 * actions in the actionsForMatch method. Do not call any of the action methods 0141 * within this method! 0142 * 0143 * Execution of the correct action should be handled in the run method. 0144 * @caution This method needs to be thread-safe since KRunner will simply 0145 * start a new thread for each new term. 0146 * 0147 * @warning Returning from this method means to end execution of the runner. 0148 * 0149 * @sa run(), RunnerContext::addMatch, RunnerContext::addMatches, QueryMatch 0150 */ 0151 virtual void match(Plasma::RunnerContext &context); 0152 0153 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81) 0154 /** 0155 * Triggers a call to match. This will call match() internally. 0156 * 0157 * @param context the search context used in executing this match. 0158 * @deprecated Since 5.81, use match(Plasma::RunnerContext &context) instead. 0159 * This method contains logic to delay slow runners, which is now deprecated. Consequently you 0160 * should call match(Plasma::RunnerContext &context) directly. 0161 */ 0162 KRUNNER_DEPRECATED_VERSION(5, 81, "use match(Plasma::RunnerContext &context) instead") 0163 void performMatch(Plasma::RunnerContext &context); 0164 #endif 0165 0166 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71) 0167 /** 0168 * If the runner has options that the user can interact with to modify 0169 * what happens when run or one of the actions created in match 0170 * is called, the runner should return true 0171 * @deprecated Since 5.0, this feature has been defunct 0172 */ 0173 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed") 0174 bool hasRunOptions(); 0175 #endif 0176 0177 #if KRUNNER_BUILD_DEPRECATED_SINCE(5, 71) 0178 /** 0179 * If hasRunOptions() returns true, this method may be called to get 0180 * a widget displaying the options the user can interact with to modify 0181 * the behaviour of what happens when a given match is selected. 0182 * 0183 * @param widget the parent of the options widgets. 0184 * @deprecated Since 5.0, this feature has been defunct 0185 */ 0186 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed") 0187 virtual void createRunOptions(QWidget *widget); 0188 #endif 0189 0190 /** 0191 * Called whenever an exact or possible match associated with this 0192 * runner is triggered. 0193 * 0194 * @param context The context in which the match is triggered, i.e. for which 0195 * the match was created. 0196 * @param match The actual match to run/execute. 0197 */ 0198 virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match); 0199 0200 #if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76) 0201 /** 0202 * Return a list of categories that this runner provides. By default 0203 * this list just contains the runners name. It is used by the runner manager 0204 * to disable certain runners if all the categories they provide have 0205 * been disabled. 0206 * 0207 * This list of categories is also used to provide a better way to 0208 * configure the runner instead of the typical on / off switch. 0209 * @deprecated Since 5.76, feature is unused. You can still set the category property in the QueryMatch 0210 */ 0211 KRUNNER_DEPRECATED_VERSION(5, 76, "Feature is unused") 0212 virtual QStringList categories() const; 0213 #endif 0214 0215 #if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76) 0216 /** 0217 * Returns the icon which accurately describes the category \p category. 0218 * This is meant to be used in a configuration dialog when showing 0219 * all the categories. 0220 * 0221 * By default this returns the icon of the AbstractRunner 0222 * * @deprecated Since 5.0, feature removed 0223 */ 0224 KRUNNER_DEPRECATED_VERSION_BELATED(5, 76, 5, 0, "No longer use, feature removed") 0225 virtual QIcon categoryIcon(const QString &category) const; 0226 #endif 0227 0228 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81) 0229 /** 0230 * The nominal speed of the runner. 0231 * @see setSpeed 0232 */ 0233 KRUNNER_DEPRECATED_VERSION(5, 81, "the concept of delayed runners is deprecated, see method docs of setSpeed(Speed) for details") 0234 Speed speed() const; 0235 #endif 0236 0237 /** 0238 * The priority of the runner. 0239 * @see setPriority 0240 */ 0241 Priority priority() const; 0242 0243 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76) 0244 /** 0245 * Returns the OR'ed value of all the Information types (as defined in RunnerContext::Type) 0246 * this runner is not interested in. 0247 * @return OR'ed value of black listed types 0248 * @deprecated This feature is deprecated 0249 */ 0250 KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated") 0251 RunnerContext::Types ignoredTypes() const; 0252 #endif 0253 0254 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76) 0255 /** 0256 * Sets the types this runner will ignore. If the value from RunnerContext::type() is contained in the ignored types 0257 * the match() method won't be called. This way there is no unnecessary thread spawned. The same RunnerContext from 0258 * which the type gets read is later passed into the match(Plasma::RunnerContext &context) method call. 0259 * @param types OR'ed listed of ignored types 0260 * @deprecated feature is deprecated. Consider using the minLetterCount and matchRegex properties instead. These 0261 * properties also prevent thread spawning, but can be used far more precise. 0262 * If you want to have this kind of optimization for older KRunner versions you could wrap this 0263 * inside of an version if statement: 0264 * @code 0265 #if KRUNNER_VERSION < QT_VERSION_CHECK(5, 76, 0) 0266 //set ignore types 0267 #endif 0268 * @endcode 0269 * The minLetterCount and matchRegex can be set with a similar version check or added to the desktop file. 0270 * If an older KRunner version loads such a desktop file these unknown properties are just ignored. 0271 * @see minLetterCount 0272 * @see matchRegex 0273 */ 0274 KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated. Consider using the minLetterCount and matchRegex properties instead") 0275 void setIgnoredTypes(RunnerContext::Types types); 0276 #endif 0277 0278 /** 0279 * @return the user visible engine name for the Runner 0280 */ 0281 QString name() const; 0282 0283 /** 0284 * @return an id string for the Runner 0285 */ 0286 QString id() const; 0287 0288 /** 0289 * @return the description of this Runner 0290 */ 0291 QString description() const; 0292 0293 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72) 0294 /** 0295 * @return the plugin info for this runner 0296 * @deprecated since 5.72, use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs 0297 */ 0298 KRUNNER_DEPRECATED_VERSION(5, 72, "Use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs") 0299 KPluginInfo metadata() const; 0300 #endif 0301 0302 /** 0303 * @return the plugin metadata for this runner 0304 * 0305 * Overload to get non-deprecated metadata format. Use like this: 0306 * @code 0307 * KPluginMetaData md = runner->metadata(Plasma::RunnerReturnPluginMetaData); 0308 * @endcode 0309 * If you disable the deprecated version using the KRUNNER_DISABLE_DEPRECATED_BEFORE_AND_AT macro, 0310 * then you can omit Plasma::RunnerReturnPluginMetaDataConstant and use it like this: 0311 * @code 0312 * KPluginMetaData md = runner->metadata(); 0313 * @endcode 0314 * 0315 * @since 5.72 0316 */ 0317 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72) 0318 KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant) const; 0319 #else 0320 KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant = RunnerReturnPluginMetaData) const; 0321 #endif 0322 /** 0323 * @return the icon for this Runner 0324 */ 0325 QIcon icon() const; 0326 0327 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65) // not 5.28 here, this KRUNNER visibility control only added at 5.65 0328 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28) // Plasma::Package is defined with this condition 0329 /** 0330 * Accessor for the associated Package object if any. 0331 * 0332 * Note that the returned pointer is only valid for the lifetime of 0333 * the runner. 0334 * 0335 * @return the Package object, which may be invalid 0336 * @deprecated since 5.28, use KPackage::Package instead, no accessor in this class 0337 **/ 0338 KRUNNER_DEPRECATED_VERSION(5, 28, "No longer use, feature removed") 0339 Package package() const; 0340 #endif 0341 #endif 0342 0343 /** 0344 * Signal runner to reload its configuration. 0345 */ 0346 virtual void reloadConfiguration(); 0347 0348 /** 0349 * @return the syntaxes the runner has registered that it accepts and understands 0350 * @since 4.3 0351 */ 0352 QList<RunnerSyntax> syntaxes() const; 0353 0354 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76) 0355 /** 0356 * @return the default syntax for the runner or @c nullptr if no default syntax has been defined 0357 * 0358 * @since 4.4 0359 * @deprecated Since 5.76, feature is unused. 0360 */ 0361 KRUNNER_DEPRECATED_VERSION(5, 76, "No longer use, feature is unused") 0362 RunnerSyntax *defaultSyntax() const; 0363 #endif 0364 0365 /** 0366 * @return true if the runner is currently busy with non-interuptable work, signaling that 0367 * new threads should not be created for it at this time 0368 * @since 4.6 0369 */ 0370 bool isMatchingSuspended() const; 0371 0372 /** 0373 * This is the minimum letter count for the query. If the query is shorter than this value 0374 * and KRunner is not in the singleRunnerMode, the performMatch and consequently match method is not called. 0375 * This can be set using the X-Plasma-Runner-Min-Letter-Count property or the setMinLetterCount method. 0376 * @see setMinLetterCount 0377 * @see match 0378 * @see performMatch 0379 * @return minLetterCount property 0380 * @since 5.75 0381 */ 0382 int minLetterCount() const; 0383 0384 /** 0385 * Set the minLetterCount property 0386 * @param count 0387 * @since 5.75 0388 */ 0389 void setMinLetterCount(int count); 0390 0391 /** 0392 * If this regex is set with a not empty pattern it must match the query in 0393 * order for the performMatch/match being called. 0394 * Just like the minLetterCount property this check is ignored when the runner is in the singleRunnerMode. 0395 * In case both the regex and the letter count is set the letter count is checked first. 0396 * @return matchRegex property 0397 * @see hasMatchRegex 0398 * @since 5.75 0399 */ 0400 QRegularExpression matchRegex() const; 0401 0402 /** 0403 * Set the matchRegex property 0404 * @param regex 0405 * @since 5.75 0406 */ 0407 void setMatchRegex(const QRegularExpression ®ex); 0408 0409 /** 0410 * Constructs internally a regex which requires the query to start with the trigger words. 0411 * Multiple words are concatenated with or, for instance: "^word1|word2|word3". 0412 * The trigger words are internally escaped. 0413 * Also the minLetterCount is set to the shortest word in the list. 0414 * @since 5.75 0415 * @see matchRegex 0416 */ 0417 void setTriggerWords(const QStringList &triggerWords); 0418 0419 /** 0420 * If the runner has a valid regex and non empty regex 0421 * @return hasMatchRegex 0422 * @since 5.75 0423 */ 0424 bool hasMatchRegex() const; 0425 0426 Q_SIGNALS: 0427 /** 0428 * This signal is emitted when matching is about to commence, giving runners 0429 * an opportunity to prepare themselves, e.g. loading data sets or preparing 0430 * IPC or network connections. This method should be fast so as not to cause 0431 * slow downs. Things that take longer or which should be loaded once and 0432 * remain extant for the lifespan of the AbstractRunner should be done in init(). 0433 * @see init() 0434 * @since 4.4 0435 */ 0436 void prepare(); 0437 0438 /** 0439 * This signal is emitted when a session of matches is complete, giving runners 0440 * the opportunity to tear down anything set up as a result of the prepare() 0441 * method. 0442 * @since 4.4 0443 */ 0444 void teardown(); 0445 0446 /** 0447 * Emitted when the runner enters or exits match suspension 0448 * @see matchingSuspended 0449 * @since 4.6 0450 */ 0451 void matchingSuspended(bool suspended); 0452 0453 protected: 0454 friend class RunnerManager; 0455 friend class RunnerManagerPrivate; 0456 0457 /** 0458 * Constructor for a KRunner plugin 0459 * @param parent parent object for this runner 0460 * @param pluginMetaData metadata that was embedded in the runner 0461 * @param args for compatibility with KPluginFactory, should be passed on to the parent constructor 0462 * @since 5.72 0463 */ 0464 AbstractRunner(QObject *parent, const KPluginMetaData &pluginMetaData, const QVariantList &args); 0465 0466 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77) 0467 KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)") 0468 explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString()); 0469 #else 0470 explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString()) = delete; 0471 #endif 0472 0473 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72) 0474 #if KSERVICE_BUILD_DEPRECATED_SINCE(5, 0) 0475 /// @deprecated Since 5.72, use AbstractRunner(const KPluginMetaData &, QObject *) 0476 KRUNNER_DEPRECATED_VERSION(5, 72, "use AbstractRunner(const KPluginMetaData &, QObject *)") 0477 explicit AbstractRunner(const KService::Ptr service, QObject *parent = nullptr); 0478 #endif 0479 #endif 0480 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86) 0481 /// @since 5.72 0482 explicit AbstractRunner(const KPluginMetaData &pluginMetaData, QObject *parent = nullptr); 0483 #endif 0484 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77) 0485 /// @deprecated Since 5.77, use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &) 0486 KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)") 0487 AbstractRunner(QObject *parent, const QVariantList &args); 0488 #endif 0489 0490 /** 0491 * Sets whether or not the runner is available for match requests. Useful to 0492 * prevent more thread spawning when the thread is in a busy state. 0493 */ 0494 void suspendMatching(bool suspend); 0495 0496 /** 0497 * Provides access to the runner's configuration object. 0498 */ 0499 KConfigGroup config() const; 0500 0501 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71) 0502 /** 0503 * Sets whether or not the runner has options for matches 0504 * @deprecated Since 5.0, this feature has been defunct 0505 */ 0506 KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed") 0507 void setHasRunOptions(bool hasRunOptions); 0508 #endif 0509 0510 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81) 0511 /** 0512 * Sets the nominal speed of the runner. Only slow runners need 0513 * to call this within their constructor because the default 0514 * speed is NormalSpeed. Runners that use D-Bus should call 0515 * this within their constructors. 0516 * @deprecated Since 5.81, the concept of delayed runners is deprecated. 0517 * If you have resource or memory intensive tasks consider porting the runner to a D-Bus runner. 0518 * Otherwise you can set the priority of the runner to LowPriority and implement the wait using a QTimer and an 0519 * event loop. It is important to check if the RunnerContext is still valid after the waiting interval. 0520 */ 0521 KRUNNER_DEPRECATED_VERSION(5, 81, "the concept of delayed runners is deprecated, see method docs for porting instructions") 0522 void setSpeed(Speed newSpeed); 0523 #endif 0524 0525 /** 0526 * Sets the priority of the runner. Lower priority runners are executed 0527 * only after higher priority runners. 0528 */ 0529 void setPriority(Priority newPriority); 0530 0531 /** 0532 * A given match can have more than action that can be performed on it. 0533 * For example, a song match returned by a music player runner can be queued, 0534 * added to the playlist, or played. 0535 * 0536 * Call this method to add actions that can be performed by the runner. 0537 * Actions must first be added to the runner's action registry. 0538 * Note: execution of correct action is left up to the runner. 0539 */ 0540 virtual QList<QAction *> actionsForMatch(const Plasma::QueryMatch &match); 0541 0542 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86) 0543 /** 0544 * Creates and then adds an action to the action registry. 0545 * AbstractRunner assumes ownership of the created action. 0546 * 0547 * @see QueryMatch::setActions 0548 * @see actionsForMatch 0549 * 0550 * @param id A unique identifier string 0551 * @param icon The icon to display 0552 * @param text The text to display 0553 * @return the created QAction 0554 * @deprecated Since 5.86 create the QAction instance manually 0555 * @code 0556 * // in the runner class definition 0557 * QList<QAction *> m_actions; 0558 * // when initializing the runner, optionally set the date if needed 0559 * auto action = new QAction(QIcon::fromTheme(iconName), text, this); 0560 * m_actions << action; 0561 * // when creating the match 0562 * match.setActions(m_actions); 0563 * @endcode 0564 */ 0565 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually") 0566 QAction *addAction(const QString &id, const QIcon &icon, const QString &text); 0567 0568 /** 0569 * Adds an action to the runner's action registry. 0570 * 0571 * The QAction must be created within the GUI thread; 0572 * do not create it within the match method of AbstractRunner. 0573 * 0574 * @param id A unique identifier string 0575 * @param action The QAction to be stored 0576 * @deprecated Since 5.86, create the QAction instance manually 0577 */ 0578 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually") 0579 void addAction(const QString &id, QAction *action); 0580 0581 /** 0582 * Removes the action from the action registry. 0583 * AbstractRunner deletes the action once removed. 0584 * 0585 * @param id The id of the action to be removed 0586 * @deprecated Since 5.86, deprecated for lack of usage 0587 */ 0588 KRUNNER_DEPRECATED_VERSION(5, 86, "deprecated for lack of usage") 0589 void removeAction(const QString &id); 0590 0591 /** 0592 * Returns the action associated with the id 0593 * @deprecated Since 5.86, create the QAction instances manually and store them in a custom container instead 0594 */ 0595 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead") 0596 QAction *action(const QString &id) const; 0597 0598 /** 0599 * Returns all registered actions 0600 * @deprecated Since 5.86, create the QAction instances manually and store them in a custom container instead 0601 */ 0602 KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead") 0603 QHash<QString, QAction *> actions() const; 0604 0605 /** 0606 * Clears the action registry. 0607 * The action pool deletes the actions. 0608 * @deprecated Since 5.86, use a custom container to store the QAction instances instead 0609 */ 0610 KRUNNER_DEPRECATED_VERSION(5, 86, "use a custom container to store the QAction instances instead") 0611 void clearActions(); 0612 #endif 0613 0614 /** 0615 * Adds a registered syntax that this runner understands. This is used to 0616 * display to the user what this runner can understand and how it can be 0617 * used. 0618 * 0619 * @param syntax the syntax to register 0620 * @since 4.3 0621 */ 0622 void addSyntax(const RunnerSyntax &syntax); 0623 0624 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76) 0625 /** 0626 * Set @p syntax as the default syntax for the runner; the default syntax will be 0627 * substituted to the empty query in single runner mode. This is also used to 0628 * display to the user what this runner can understand and how it can be 0629 * used. 0630 * The default syntax is automatically added to the list of registered syntaxes, there 0631 * is no need to add it using addSyntax. 0632 * Note that there can be only one default syntax; if called more than once, the last 0633 * call will determine the default syntax. 0634 * A default syntax (even trivial) is required to advertise single runner mode 0635 * 0636 * @param syntax the syntax to register and to set as default 0637 * @since 4.4 0638 * @deprecated Since 5.76, feature is unused. Use addSyntax() instead. 0639 **/ 0640 KRUNNER_DEPRECATED_VERSION(5, 76, "Feature unused, use addSyntax() instead") 0641 void setDefaultSyntax(const RunnerSyntax &syntax); 0642 #endif 0643 0644 /** 0645 * Utility overload for creating a syntax based on the given parameters 0646 * @see RunnerSyntax 0647 * @since 5.106 0648 */ 0649 inline void addSyntax(const QString &exampleQuery, const QString &description) 0650 { 0651 addSyntax(QStringList(exampleQuery), description); 0652 } 0653 0654 /// @copydoc addSyntax(const QString &exampleQuery, const QString &description) 0655 inline void addSyntax(const QStringList &exampleQueries, const QString &description) 0656 { 0657 addSyntax(RunnerSyntax(exampleQueries, description)); 0658 } 0659 0660 /** 0661 * Sets the list of syntaxes; passing in an empty list effectively clears 0662 * the syntaxes. 0663 * 0664 * @param the syntaxes to register for this runner 0665 * @since 4.3 0666 */ 0667 void setSyntaxes(const QList<RunnerSyntax> &syns); 0668 0669 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 73) 0670 /** 0671 * Loads the given DataEngine 0672 * 0673 * Tries to load the data engine given by @p name. Each engine is 0674 * only loaded once, and that instance is re-used on all subsequent 0675 * requests. 0676 * 0677 * If the data engine was not found, an invalid data engine is returned 0678 * (see DataEngine::isValid()). 0679 * 0680 * Note that you should <em>not</em> delete the returned engine. 0681 * 0682 * @param name Name of the data engine to load 0683 * @return pointer to the data engine if it was loaded, 0684 * or an invalid data engine if the requested engine 0685 * could not be loaded 0686 * 0687 * @since 4.4 0688 * @deprecated Since 5.73, DataEngines are deprecated, use e.g. a shared library to provide the data instead. 0689 */ 0690 KRUNNER_DEPRECATED_VERSION(5, 73, "DataEngines are deprecated, use e.g. a shared library to provide the data instead.") 0691 Q_INVOKABLE DataEngine *dataEngine(const QString &name) const; 0692 #endif 0693 0694 /** 0695 * Reimplement this slot to run any initialization routines on first load. 0696 * By default, it calls reloadConfiguration(); for scripted Runners this 0697 * method also sets up the ScriptEngine. 0698 */ 0699 virtual void init(); 0700 0701 /** 0702 * Reimplement this slot if you want your runner 0703 * to support serialization and drag and drop 0704 * @since 4.5 0705 */ 0706 virtual QMimeData *mimeDataForMatch(const Plasma::QueryMatch &match); 0707 0708 private: 0709 std::unique_ptr<AbstractRunnerPrivate> const d; 0710 KRUNNER_NO_EXPORT bool hasUniqueResults(); 0711 KRUNNER_NO_EXPORT bool hasWeakResults(); 0712 friend class RunnerContext; 0713 friend class RunnerContextPrivate; 0714 friend class QueryMatch; 0715 }; 0716 0717 } // Plasma namespace 0718 0719 // clang-format off 0720 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72) 0721 // Boilerplate to emit a version-controlled warning about the deprecated macro at least with GCC 0722 #if KRUNNER_DEPRECATED_WARNINGS_SINCE >= 0x054800 // 5.72.0 0723 # if defined(__GNUC__) 0724 # define K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(x) _Pragma (#x) 0725 # define K_EXPORT_PLASMA_RUNNER_WARNING(x) K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(message(#x)) 0726 # else 0727 # define K_EXPORT_PLASMA_RUNNER_WARNING(x) 0728 # endif 0729 #else 0730 # define K_EXPORT_PLASMA_RUNNER_WARNING(x) 0731 #endif 0732 /** 0733 * @relates Plasma::AbstractRunner 0734 * 0735 * Registers a runner plugin. 0736 * 0737 * @deprecated Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead 0738 */ 0739 #define K_EXPORT_PLASMA_RUNNER( libname, classname ) \ 0740 K_EXPORT_PLASMA_RUNNER_WARNING("Deprecated. Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead") \ 0741 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) 0742 #endif 0743 0744 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 88) 0745 /** 0746 * @relates Plasma::AbstractRunner 0747 * 0748 * Registers a runner plugin with JSON metadata. 0749 * 0750 * @param classname name of the AbstractRunner derived class. 0751 * @param jsonFile name of the JSON file to be compiled into the plugin as metadata 0752 * 0753 * @since 5.72 0754 * @deprecated Since 5.88 use K_PLUGIN_CLASS_WITH_JSON instead 0755 */ 0756 #define K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) \ 0757 K_PLUGIN_FACTORY_WITH_JSON(classname ## Factory, jsonFile, registerPlugin<classname>();) 0758 #endif 0759 0760 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 75) 0761 /** 0762 * These plugins are Used by the plugin selector dialog to show 0763 * configuration options specific to this runner. These options 0764 * must be runner global and not pertain to a specific match. 0765 * @deprecated Since 5.0, use K_PLUGIN_FACTORY directly 0766 */ 0767 #define K_EXPORT_RUNNER_CONFIG( name, classname ) \ 0768 K_PLUGIN_FACTORY(ConfigFactory, registerPlugin<classname>();) 0769 #endif 0770 // clang-format on 0771 0772 #if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91) 0773 namespace KRunner 0774 { 0775 using AbstractRunner = Plasma::AbstractRunner; 0776 using RunnerContext = Plasma::RunnerContext; 0777 } 0778 #endif 0779 0780 #endif