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 RunnerSyntax runnersyntax.h <KRunner/RunnerSyntax>
21 *
22 * Represents a query prototype that the runner accepts. These can be
23 * created and registered with AbstractRunner::addSyntax to
24 * allow applications to show to the user what the runner is currently capable of doing.
25 *
26 * Lets say the runner has a trigger word and then the user can type anything after that. In that case you could use
27 * ":q:" as a placeholder, which will get expanded to i18n("search term") and be put in brackets.
28 * @code
29 KRunner::RunnerSyntax syntax(QStringLiteral("sometriggerword :q:"), i18n("Description for this syntax"));
30 addSyntax(syntax);
31 * @endcode
32 *
33 * But if the query the user has to enter is sth. specific like a program,
34 * url or file you should use a custom placeholder to make it easier to understand.
35 * @code
36 KRunner::RunnerSyntax syntax(QStringLiteral("sometriggereword <%1>").arg(i18n("program name"))), i18n("Description for this syntax"));
37 addSyntax(syntax);
38 * @endcode
39 */
40class KRUNNER_EXPORT RunnerSyntax
41{
42public:
43 /**
44 * Constructs a RunnerSyntax with one example query
45 *
46 * @param exampleQuery See the class description for examples and placeholder conventions.
47 * @param description A description of what the described syntax does from the user's point of view.
48 */
49 explicit inline RunnerSyntax(const QString &exampleQuery, const QString &description)
50 : RunnerSyntax(QStringList(exampleQuery), description)
51 {
52 }
53
54 /**
55 * Constructs a RunnerSyntax with multiple example queries
56 *
57 * @param exampleQueries See the class description for examples and placeholder conventions.
58 * @param description A description of what the described syntax does from the user's point of view.
59 * This description should be true for all example queries. In case they differ, consider using multiple syntaxes.
60 *
61 * @since 5.106
62 */
63 explicit RunnerSyntax(const QStringList &exampleQueries, const QString &description);
64
65 ~RunnerSyntax();
66
67 /**
68 * @return the example queries associated with this Syntax object
69 */
70 QStringList exampleQueries() const;
71
72 /**
73 * @return the user visible description of what the syntax does
74 */
75 QString description() const;
76
77 /// @internal
78 RunnerSyntax &operator=(const RunnerSyntax &rhs);
79 /// @internal
80 explicit RunnerSyntax(const RunnerSyntax &other);
81
82private:
83 std::unique_ptr<RunnerSyntaxPrivate> d;
84};
85
86} // namespace KRunner
87
88#endif // multiple inclusion guard
89

source code of krunner/src/runnersyntax.h