KRunner

runnersyntax.h
1 /*
2  SPDX-FileCopyrightText: 2009 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_RUNNERSYNTAX_H
8 #define PLASMA_RUNNERSYNTAX_H
9 
10 #include <QStringList>
11 #include <memory>
12 
13 #include "krunner_export.h"
14 
15 namespace Plasma
16 {
17 class RunnerSyntaxPrivate;
18 /**
19  * @class RunnerSyntax runnersyntax.h <KRunner/RunnerSyntax>
20  * @since 4.3
21  *
22  * Represents a query prototype that the runner accepts. These can be
23  * created and registered with AbstractRunner::addSyntax(Syntax &) to
24  * allow applications to show to the user what the runner is currently
25  * capable of doing.
26  *
27  * Lets say the runner has a trigger word and then the user can type anything after that. In that case you could use
28  * ":q:" as a placeholder, which will get expanded to i18n("search term") and be put in brackets.
29  * @code
30  Plasma::RunnerSyntax syntax(QStringLiteral("sometriggerword :q:"), i18n("Description for this syntax"));
31  addSyntax(syntax);
32  * @endcode
33  *
34  * But if the query the user has to enter is sth. specific like a program,
35  * url or file you should use a custom placeholder to make it easier to understand.
36  * @code
37  Plasma::RunnerSyntax syntax(QStringLiteral("sometriggereword <%1>").arg(i18n("program name"))), i18n("Description for this syntax"));
38  addSyntax(syntax);
39  * @endcode
40  */
41 class KRUNNER_EXPORT RunnerSyntax
42 {
43 public:
44  /**
45  * Constructs a simple syntax object
46  *
47  * @param exampleQuery See the class description for examples and placeholder conventions.
48  * @param description A description of what the described syntax does from
49  * the user's point of view.
50  */
51  RunnerSyntax(const QString &exampleQuery, const QString &description);
52 
53  /**
54  * Constructs a syntax object
55  *
56  * @param exampleQuery See the class description for examples and placeholder conventions.
57  * @param description A description of what the described syntax does from the user's point of view.
58  *
59  * @since 5.106
60  */
61  explicit RunnerSyntax(const QStringList &exampleQueries, const QString &description);
62 
63  /**
64  * Copy constructor
65  */
66  RunnerSyntax(const RunnerSyntax &other);
67 
68  ~RunnerSyntax();
69 
70  /**
71  * Assignment operator
72  */
73  RunnerSyntax &operator=(const RunnerSyntax &rhs);
74 
75 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 106)
76  /**
77  * Adds a synonymous example query to this Syntax. Some runners may
78  * accept multiple formulations of keywords to trigger the same behaviour.
79  * This allows the runner to show these relationships by grouping the
80  * example queries into one Syntax object
81  *
82  * @param exampleQuery See the class description for examples and placeholder conventions.
83  * @deprecated Since 5.106, use constructor taking example query QStringList
84  */
85  KRUNNER_DEPRECATED_VERSION(5, 106, "Use constructor taking example query QStringList")
86  void addExampleQuery(const QString &exampleQuery);
87 #endif
88 
89  /**
90  * @return the example queries associated with this Syntax object
91  */
92  QStringList exampleQueries() const;
93 
94 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
95  /**
96  * @return the example queries associated with this Syntax object, with
97  * the searchTermDescription replacing instances of :q:. Used for showing
98  * the queries in the user interface.
99  * @deprecated Since 5.76, the description should be directly set when creating the example query.
100  * To display the queries in the user interface. Use exampleQueries() instead.
101  */
102  KRUNNER_DEPRECATED_VERSION(5, 76, "The descriptions should be directly set when creating the example query. Use exampleQueries() instead.")
103  QStringList exampleQueriesWithTermDescription() const;
104 #endif
105 
106 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 106)
107  /**
108  * Sets the description for the syntax, describing what it does from
109  * the user's point of view.
110  * @deprecated Since 5.106, this should only be set when constructing the syntax
111  */
112  KRUNNER_DEPRECATED_VERSION(5, 106, "This should only be set when constructing the syntax")
113  void setDescription(const QString &description);
114 #endif
115 
116  /**
117  * @return the description of what the syntax does from the user's
118  * point of view
119  */
120  QString description() const;
121 
122 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
123  /**
124  * Sets the text that should be used to replace instances of :q:
125  * in the text. By default this is the generic phrase "search term".
126  * If the syntax expects a specific kind of input, it may be defined
127  * here. A syntax used by a runner that changes the brightness of the display
128  * may set this to "brightness" for instance.
129  * @deprecated Since 5.76, set the description directly when creating the example query. Use <my query description> instead of :q: when creating the string
130  */
131  KRUNNER_DEPRECATED_VERSION(
132  5,
133  76,
134  "Set the description directly when creating the example query. Use <my query description> instead of :q: when creating the string")
135  void setSearchTermDescription(const QString &description);
136 #endif
137 
138 #if KRUNNER_ENABLE_DEPRECATED_SINCE(5, 76)
139  /**
140  * @return a description of the search term for this syntax
141  * @deprecated Since 5.76, the description should be directly set when creating the example query.
142  */
143  KRUNNER_DEPRECATED_VERSION(5, 76, "Feature is obsolete, the search term description should be set inside of the example query directly")
144  QString searchTermDescription() const;
145 #endif
146 
147 private:
148  std::unique_ptr<RunnerSyntaxPrivate> const d;
149 };
150 
151 } // namespace Plasma
152 
153 #if !KRUNNER_ENABLE_DEPRECATED_SINCE(5, 91)
154 namespace KRunner
155 {
156 using RunnerSyntax = Plasma::RunnerSyntax;
157 }
158 #endif
159 
160 #endif // multiple inclusion guard
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 03:51:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.