1 | /* |
2 | * Copyright 2009 Aaron Seigo <aseigo@kde.org> |
3 | * |
4 | * This program is free software; you can redistribute it and/or modify |
5 | * it under the terms of the GNU Library General Public License as |
6 | * published by the Free Software Foundation; either version 2, or |
7 | * (at your option) any later version. |
8 | * |
9 | * This program is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
12 | * GNU General Public License for more details |
13 | * |
14 | * You should have received a copy of the GNU Library General Public |
15 | * License along with this program; if not, write to the |
16 | * Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef PLASMA_RUNNERSYNTAX_H |
21 | #define PLASMA_RUNNERSYNTAX_H |
22 | |
23 | #include <QtCore/QStringList> |
24 | |
25 | #include <plasma/plasma.h> |
26 | |
27 | namespace Plasma |
28 | { |
29 | |
30 | class RunnerSyntaxPrivate; |
31 | /** |
32 | * @class RunnerSyntax |
33 | * @since 4.3 |
34 | * |
35 | * Represents a query prototype that the runner accepts. These can be |
36 | * created and registered with AbstractRunner::addSyntax(Syntax &) to |
37 | * allow applications to show to the user what the runner is currently |
38 | * capable of doing |
39 | */ |
40 | class PLASMA_EXPORT RunnerSyntax |
41 | { |
42 | public: |
43 | /** |
44 | * Constructs a simple syntax object |
45 | * |
46 | * @param exampleQuery an example of the query, with :q: placed wherever |
47 | * search term text might appear. e.g. if the runner |
48 | * accepts "keyword some random text" then the value |
49 | * of this parameter should be "keyword :q:" |
50 | * @param descrition A description of what the described syntax does from |
51 | * the user's point of view. |
52 | */ |
53 | RunnerSyntax(const QString &exampleQuery, const QString &description); |
54 | |
55 | /** |
56 | * Copy constructor |
57 | */ |
58 | RunnerSyntax(const RunnerSyntax &other); |
59 | |
60 | ~RunnerSyntax(); |
61 | |
62 | /** |
63 | * Assignment operator |
64 | */ |
65 | RunnerSyntax &operator=(const RunnerSyntax &rhs); |
66 | |
67 | /** |
68 | * Adds a synonymous example query to this Syntax. Some runners may |
69 | * accept multiple formulations of keywords to trigger the same behaviour. |
70 | * This allows the runner to show these relationships by grouping the |
71 | * example queries into one Syntax object |
72 | * |
73 | * @param exampleQuery an example of the query, with :q: placed wherever |
74 | * search term text might appear. e.g. if the runner |
75 | * accepts "keyword some random text" then the value |
76 | * of this parameter should be "keyword :q:" |
77 | */ |
78 | void addExampleQuery(const QString &exampleQuery); |
79 | |
80 | /** |
81 | * @return the example queries associated with this Syntax object |
82 | */ |
83 | QStringList exampleQueries() const; |
84 | |
85 | /** |
86 | * @return the example queries associated with this Syntax object, with |
87 | * the searchTermDescription replacing instances of :q:. Used for showing |
88 | * the queries in the user interface. |
89 | */ |
90 | QStringList exampleQueriesWithTermDescription() const; |
91 | |
92 | /** |
93 | * Sets the description for the syntax, describing what it does from |
94 | * the user's point of view. |
95 | */ |
96 | void setDescription(const QString &description); |
97 | |
98 | /** |
99 | * @return the description of what the syntax does from the user's |
100 | * point of view |
101 | */ |
102 | QString description() const; |
103 | |
104 | /** |
105 | * Sets the text that should be used to replace instances of :q: |
106 | * in the text. By default this is the generic phrase "search term". |
107 | * If the syntax expects a specific kind of input, it may be defined |
108 | * here. A syntax used by a runner that changes the brightness of the display |
109 | * may set this to "brightness" for instance. |
110 | */ |
111 | void setSearchTermDescription(const QString &description); |
112 | |
113 | /** |
114 | * @return a description of the search term for this syntax |
115 | */ |
116 | QString searchTermDescription() const; |
117 | |
118 | private: |
119 | RunnerSyntaxPrivate *const d; |
120 | }; |
121 | |
122 | } // namespace Plasma |
123 | |
124 | #endif // multiple inclusion guard |
125 | |
126 | |