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
27namespace Plasma
28{
29
30class 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 */
40class 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