File indexing completed on 2024-04-28 15:29:45

 /*
     SPDX-FileCopyrightText: 2009 Aaron Seigo <aseigo@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef PLASMA_RUNNERSYNTAX_H
 #define PLASMA_RUNNERSYNTAX_H
 
 #include <QStringList>
 #include <memory>
 
 #include "krunner_export.h"
 
 namespace Plasma
 {
 class RunnerSyntaxPrivate;
 /**
  * @class RunnerSyntax runnersyntax.h <KRunner/RunnerSyntax>
  * @since 4.3
  *
  * Represents a query prototype that the runner accepts. These can be
  * created and registered with AbstractRunner::addSyntax(Syntax &) to
  * allow applications to show to the user what the runner is currently
  * capable of doing.
  *
  * Lets say the runner has a trigger word and then the user can type anything after that. In that case you could use
  * ":q:" as a placeholder, which will get expanded to i18n("search term") and be put in brackets.
  * @code
    Plasma::RunnerSyntax syntax(QStringLiteral("sometriggerword :q:"), i18n("Description for this syntax"));
    addSyntax(syntax);
  * @endcode
  *
  * But if the query the user has to enter is sth. specific like a program,
  * url or file you should use a custom placeholder to make it easier to understand.
  * @code
    Plasma::RunnerSyntax syntax(QStringLiteral("sometriggereword <%1>").arg(i18n("program name"))), i18n("Description for this syntax"));
    addSyntax(syntax);
  * @endcode
  */
 class KRUNNER_EXPORT RunnerSyntax
 {
 public:
     /**
      * Constructs a simple syntax object
      *
      * @param exampleQuery See the class description for examples and placeholder conventions.
      * @param description A description of what the described syntax does from
      *                    the user's point of view.
      */
     RunnerSyntax(const QString &exampleQuery, const QString &description);
 
     /**
      * Constructs a syntax object
      *
      * @param exampleQuery See the class description for examples and placeholder conventions.
      * @param description A description of what the described syntax does from the user's point of view.
      *
      * @since 5.106
      */
     explicit RunnerSyntax(const QStringList &exampleQueries, const QString &description);
 
     /**
      * Copy constructor
      */
     RunnerSyntax(const RunnerSyntax &other);
 
     ~RunnerSyntax();
 
     /**
      * Assignment operator
      */
     RunnerSyntax &operator=(const RunnerSyntax &rhs);
 
 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 106)
     /**
      * Adds a synonymous example query to this Syntax. Some runners may
      * accept multiple formulations of keywords to trigger the same behaviour.
      * This allows the runner to show these relationships by grouping the
      * example queries into one Syntax object
      *
      * @param exampleQuery See the class description for examples and placeholder conventions.
      * @deprecated Since 5.106, use constructor taking example query QStringList
      */
     KRUNNER_DEPRECATED_VERSION(5, 106, "Use constructor taking example query QStringList")
     void addExampleQuery(const QString &exampleQuery);
 #endif
 
     /**
      * @return the example queries associated with this Syntax object
      */
     QStringList exampleQueries() const;
 
 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
     /**
      * @return the example queries associated with this Syntax object, with
      * the searchTermDescription replacing instances of :q:. Used for showing
      * the queries in the user interface.
      * @deprecated Since 5.76, the description should be directly set when creating the example query.
      * To display the queries in the user interface. Use exampleQueries() instead.
      */
     KRUNNER_DEPRECATED_VERSION(5, 76, "The descriptions should be directly set when creating the example query. Use exampleQueries() instead.")
     QStringList exampleQueriesWithTermDescription() const;
 #endif
 
 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 106)
     /**
      * Sets the description for the syntax, describing what it does from
      * the user's point of view.
      * @deprecated Since 5.106, this should only be set when constructing the syntax
      */
     KRUNNER_DEPRECATED_VERSION(5, 106, "This should only be set when constructing the syntax")
     void setDescription(const QString &description);
 #endif
 
     /**
      * @return the description of what the syntax does from the user's
      *         point of view
      */
     QString description() const;
 
 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
     /**
      * Sets the text that should be used to replace instances of :q:
      * in the text. By default this is the generic phrase "search term".
      * If the syntax expects a specific kind of input, it may be defined
      * here. A syntax used by a runner that changes the brightness of the display
      * may set this to "brightness" for instance.
      * @deprecated Since 5.76, set the description directly when creating the example query. Use <my query description> instead of :q: when creating the string
      */
     KRUNNER_DEPRECATED_VERSION(
         5,
         76,
         "Set the description directly when creating the example query. Use <my query description> instead of :q: when creating the string")
     void setSearchTermDescription(const QString &description);
 #endif
 
 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
     /**
      * @return a description of the search term for this syntax
      * @deprecated Since 5.76, the description should be directly set when creating the example query.
      */
     KRUNNER_DEPRECATED_VERSION(5, 76, "Feature is obsolete, the search term description should be set inside of the example query directly")
     QString searchTermDescription() const;
 #endif
 
 private:
     std::unique_ptr<RunnerSyntaxPrivate> const d;
 };
 
 } // namespace Plasma
 
 #if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
 namespace KRunner
 {
 using RunnerSyntax = Plasma::RunnerSyntax;
 }
 #endif
 
 #endif // multiple inclusion guard