1/*
2 SPDX-FileCopyrightText: 2009 Aaron Seigo <aseigo@kde.org>
3 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnau@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KRUNNER_RUNNERSYNTAX_H
9#define KRUNNER_RUNNERSYNTAX_H
10
11#include <QStringList>
12#include <memory>
13
14#include "krunner_export.h"
15
16namespace KRunner
17{
18class RunnerSyntaxPrivate;
19/*!
20 * \class KRunner::RunnerSyntax
21 * \inheaderfile KRunner/RunnerSyntax
22 * \inmodule KRunner
23 *
24 * \brief Represents a query prototype that the runner accepts.
25 *
26 * These can be
27 * created and registered with AbstractRunner::addSyntax to
28 * allow applications to show to the user what the runner is currently capable of doing.
29 *
30 * Lets say the runner has a trigger word and then the user can type anything after that. In that case you could use
31 * ":q:" as a placeholder, which will get expanded to i18n("search term") and be put in brackets.
32 * \code
33 * KRunner::RunnerSyntax syntax(QStringLiteral("sometriggerword :q:"), i18n("Description for this syntax"));
34 * addSyntax(syntax);
35 * \endcode
36 *
37 * But if the query the user has to enter is sth. specific like a program,
38 * url or file you should use a custom placeholder to make it easier to understand.
39 * \code
40 * KRunner::RunnerSyntax syntax(QStringLiteral("sometriggereword <%1>").arg(i18n("program name"))), i18n("Description for this syntax"));
41 * addSyntax(syntax);
42 * \endcode
43 */
44class KRUNNER_EXPORT RunnerSyntax
45{
46public:
47 /*!
48 * Constructs a RunnerSyntax with one example query
49 *
50 * \a exampleQuery See the class description for examples and placeholder conventions.
51 *
52 * \a description A description of what the described syntax does from the user's point of view.
53 */
54 explicit inline RunnerSyntax(const QString &exampleQuery, const QString &description)
55 : RunnerSyntax(QStringList(exampleQuery), description)
56 {
57 }
58
59 /*!
60 * Constructs a RunnerSyntax with multiple example queries
61 *
62 * \a exampleQueries See the class description for examples and placeholder conventions.
63 *
64 * \a description A description of what the described syntax does from the user's point of view.
65 * This description should be true for all example queries. In case they differ, consider using multiple syntaxes.
66 *
67 * \since 5.106
68 */
69 explicit RunnerSyntax(const QStringList &exampleQueries, const QString &description);
70
71 ~RunnerSyntax();
72
73 /*!
74 * Returns the example queries associated with this Syntax object
75 */
76 QStringList exampleQueries() const;
77
78 /*!
79 * Returns the user visible description of what the syntax does
80 */
81 QString description() const;
82
83 RunnerSyntax &operator=(const RunnerSyntax &rhs);
84 explicit RunnerSyntax(const RunnerSyntax &other);
85
86private:
87 std::unique_ptr<RunnerSyntaxPrivate> d;
88};
89
90} // namespace KRunner
91
92#endif // multiple inclusion guard
93

source code of krunner/src/runnersyntax.h