abstractrunner.h

/*
    SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <aseigo@kde.org>
 
    SPDX-License-Identifier: LGPL-2.0-or-later
*/
 
#ifndef PLASMA_ABSTRACTRUNNER_H
#define PLASMA_ABSTRACTRUNNER_H
 
#include "krunner_export.h"
 
#include <QObject>
#include <QStringList>
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 94)
#include <KConfigGroup>
#include <QIcon>
#else
class KConfigGroup;
class QIcon;
#endif
#include <KPluginMetaData>
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
#include <KPluginInfo>
#include <KService>
#else
#include <KPluginFactory>
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65)
#include <plasma/plasma_export.h> // for PLASMA_ENABLE_DEPRECATED_SINCE
#include <plasma_version.h>
#endif
 
#include <memory>
 
#include "querymatch.h"
#include "runnercontext.h"
#include "runnersyntax.h"
 
class QAction;
class QMimeData;
class QRegularExpression;
 
namespace Plasma
{
class DataEngine;
class Package;
class QueryMatch;
class AbstractRunnerPrivate;
 
enum RunnerReturnPluginMetaDataConstant { RunnerReturnPluginMetaData }; // KF6: remove again
 
class KRUNNER_EXPORT AbstractRunner : public QObject
{
    Q_OBJECT
    Q_PROPERTY(bool matchingSuspended READ isMatchingSuspended WRITE suspendMatching NOTIFY matchingSuspended)
    Q_PROPERTY(QString id READ id)
    Q_PROPERTY(QString description READ description)
    Q_PROPERTY(QString name READ name)
    Q_PROPERTY(QIcon icon READ icon)
    Q_PROPERTY(int minLetterCount READ minLetterCount WRITE setMinLetterCount)
    Q_PROPERTY(QRegularExpression matchRegex READ matchRegex WRITE setMatchRegex)
 
public:
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
    enum Speed{
        SlowSpeed,
        NormalSpeed,
    };
#endif
 
    enum Priority {
        LowestPriority = 0,
        LowPriority,
        NormalPriority,
        HighPriority,
        HighestPriority,
    };
 
    typedef QList<AbstractRunner *> List;
 
    ~AbstractRunner() override;
 
    virtual void match(Plasma::RunnerContext &context);
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
    KRUNNER_DEPRECATED_VERSION(5, 81, "use match(Plasma::RunnerContext &context) instead")
    void performMatch(Plasma::RunnerContext &context);
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
    KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
    bool hasRunOptions();
#endif
 
#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 71)
    KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
    virtual void createRunOptions(QWidget *widget);
#endif
 
    virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match);
 
#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION(5, 76, "Feature is unused")
    virtual QStringList categories() const;
#endif
 
#if KRUNNER_BUILD_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION_BELATED(5, 76, 5, 0, "No longer use, feature removed")
    virtual QIcon categoryIcon(const QString &category) const;
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
    KRUNNER_DEPRECATED_VERSION(5, 81, "the concept of delayed runners is deprecated, see method docs of setSpeed(Speed) for details")
    Speed speed() const;
#endif
 
    Priority priority() const;
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated")
    RunnerContext::Types ignoredTypes() const;
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION(5, 76, "feature is deprecated. Consider using the minLetterCount and matchRegex properties instead")
    void setIgnoredTypes(RunnerContext::Types types);
#endif
 
    QString name() const;
 
    QString id() const;
 
    QString description() const;
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
    KRUNNER_DEPRECATED_VERSION(5, 72, "Use metaData(Plasma::RunnerReturnPluginMetaDataConstant) instead, see its API docs")
    KPluginInfo metadata() const;
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
    KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant) const;
#else
    KPluginMetaData metadata(RunnerReturnPluginMetaDataConstant = RunnerReturnPluginMetaData) const;
#endif
    QIcon icon() const;
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 65) // not 5.28 here, this KRUNNER visibility control only added at 5.65
#if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28) // Plasma::Package is defined with this condition
    KRUNNER_DEPRECATED_VERSION(5, 28, "No longer use, feature removed")
    Package package() const;
#endif
#endif
 
    virtual void reloadConfiguration();
 
    QList<RunnerSyntax> syntaxes() const;
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION(5, 76, "No longer use, feature is unused")
    RunnerSyntax *defaultSyntax() const;
#endif
 
    bool isMatchingSuspended() const;
 
    int minLetterCount() const;
 
    void setMinLetterCount(int count);
 
    QRegularExpression matchRegex() const;
 
    void setMatchRegex(const QRegularExpression &regex);
 
    void setTriggerWords(const QStringList &triggerWords);
 
    bool hasMatchRegex() const;
 
Q_SIGNALS:
    void prepare();
 
    void teardown();
 
    void matchingSuspended(bool suspended);
 
protected:
    friend class RunnerManager;
    friend class RunnerManagerPrivate;
 
    AbstractRunner(QObject *parent, const KPluginMetaData &pluginMetaData, const QVariantList &args);
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
    KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
    explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString());
#else
    explicit AbstractRunner(QObject *parent = nullptr, const QString &path = QString()) = delete;
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
#if KSERVICE_BUILD_DEPRECATED_SINCE(5, 0)
    KRUNNER_DEPRECATED_VERSION(5, 72, "use AbstractRunner(const KPluginMetaData &, QObject *)")
    explicit AbstractRunner(const KService::Ptr service, QObject *parent = nullptr);
#endif
#endif
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
    explicit AbstractRunner(const KPluginMetaData &pluginMetaData, QObject *parent = nullptr);
#endif
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 77)
    KRUNNER_DEPRECATED_VERSION(5, 77, "use AbstractRunner(QObject *, const KPluginMetaData &, const QVariantList &)")
    AbstractRunner(QObject *parent, const QVariantList &args);
#endif
 
    void suspendMatching(bool suspend);
 
    KConfigGroup config() const;
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 71)
    KRUNNER_DEPRECATED_VERSION_BELATED(5, 71, 5, 0, "No longer use, feature removed")
    void setHasRunOptions(bool hasRunOptions);
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 81)
    KRUNNER_DEPRECATED_VERSION(5, 81, "the concept of delayed runners is deprecated, see method docs for porting instructions")
    void setSpeed(Speed newSpeed);
#endif
 
    void setPriority(Priority newPriority);
 
    virtual QList<QAction *> actionsForMatch(const Plasma::QueryMatch &match);
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 86)
    KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
    QAction *addAction(const QString &id, const QIcon &icon, const QString &text);
 
    KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instance manually")
    void addAction(const QString &id, QAction *action);
 
    KRUNNER_DEPRECATED_VERSION(5, 86, "deprecated for lack of usage")
    void removeAction(const QString &id);
 
    KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead")
    QAction *action(const QString &id) const;
 
    KRUNNER_DEPRECATED_VERSION(5, 86, "create the QAction instances manually and store them in a custom container instead")
    QHash<QString, QAction *> actions() const;
 
    KRUNNER_DEPRECATED_VERSION(5, 86, "use a custom container to store the QAction instances instead")
    void clearActions();
#endif
 
    void addSyntax(const RunnerSyntax &syntax);
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
    KRUNNER_DEPRECATED_VERSION(5, 76, "Feature unused, use addSyntax() instead")
    void setDefaultSyntax(const RunnerSyntax &syntax);
#endif
 
    inline void addSyntax(const QString &exampleQuery, const QString &description)
    {
        addSyntax(QStringList(exampleQuery), description);
    }
 
    inline void addSyntax(const QStringList &exampleQueries, const QString &description)
    {
        addSyntax(RunnerSyntax(exampleQueries, description));
    }
 
    void setSyntaxes(const QList<RunnerSyntax> &syns);
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 73)
    KRUNNER_DEPRECATED_VERSION(5, 73, "DataEngines are deprecated, use e.g. a shared library to provide the data instead.")
    Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
#endif
 
    virtual void init();
 
    virtual QMimeData *mimeDataForMatch(const Plasma::QueryMatch &match);
 
private:
    std::unique_ptr<AbstractRunnerPrivate> const d;
    KRUNNER_NO_EXPORT bool hasUniqueResults();
    KRUNNER_NO_EXPORT bool hasWeakResults();
    friend class RunnerContext;
    friend class RunnerContextPrivate;
    friend class QueryMatch;
};
 
} // Plasma namespace
 
// clang-format off
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 72)
// Boilerplate to emit a version-controlled warning about the deprecated macro at least with GCC
#if KRUNNER_DEPRECATED_WARNINGS_SINCE >= 0x054800 // 5.72.0
#   if defined(__GNUC__)
#       define K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(x) _Pragma (#x)
#       define K_EXPORT_PLASMA_RUNNER_WARNING(x) K_EXPORT_PLASMA_RUNNER_DO_PRAGMA(message(#x))
#   else
#       define K_EXPORT_PLASMA_RUNNER_WARNING(x)
#   endif
#else
#   define K_EXPORT_PLASMA_RUNNER_WARNING(x)
#endif
#define K_EXPORT_PLASMA_RUNNER( libname, classname )     \
K_EXPORT_PLASMA_RUNNER_WARNING("Deprecated. Since 5.72, use K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) instead") \
K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 88)
#define K_EXPORT_PLASMA_RUNNER_WITH_JSON(classname, jsonFile) \
    K_PLUGIN_FACTORY_WITH_JSON(classname ## Factory, jsonFile, registerPlugin<classname>();)
#endif
 
#if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 75)
#define K_EXPORT_RUNNER_CONFIG( name, classname )     \
K_PLUGIN_FACTORY(ConfigFactory, registerPlugin<classname>();)
#endif
// clang-format on
 
#if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
namespace KRunner
{
using AbstractRunner = Plasma::AbstractRunner;
using RunnerContext = Plasma::RunnerContext;
}
#endif
 
#endif