1 | /* |
2 | This file is part of the KDE Baloo Project |
3 | SPDX-FileCopyrightText: 2013-2015 Vishesh Handa <vhanda@kde.org> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL |
6 | */ |
7 | |
8 | #ifndef BALOO_QUERY_H |
9 | #define BALOO_QUERY_H |
10 | |
11 | #include "core_export.h" |
12 | #include "resultiterator.h" |
13 | |
14 | #include <QUrl> |
15 | |
16 | #include <memory> |
17 | |
18 | namespace Baloo { |
19 | |
20 | /*! |
21 | * \class Baloo::Query |
22 | * \inheaderfile Baloo/Query |
23 | * \inmodule Baloo |
24 | * |
25 | * \brief The Query class is the central class to query to search for files from the Index. |
26 | * |
27 | * This class has an inbuilt parser which recognizes words along with AND / OR and parenthesis |
28 | * and specific properties. This can be used with the setSearchString method |
29 | * |
30 | * Examples: |
31 | * |
32 | * "Fire" -> Looks for all files which contain the word "Fire" |
33 | * |
34 | * "Fire OR water" -> Looks for files which contain either "Fire" or "Water". The capitalization |
35 | * of the words doesn't matter as that will be ignored internally. However, OR and AND have to |
36 | * be in upper case. |
37 | * |
38 | * "artist:Coldplay" -> Look for any files with the artist "Coldplay" |
39 | * |
40 | * "artist:(Coldplay OR Maroon5) power" -> Look for files with the artist Coldplay or Maroon5 and |
41 | * the word "power" |
42 | * |
43 | * "artist:'Noah and the Whale'" -> Look for files with the artist "Noah and the Whale" |
44 | * |
45 | * "type:Audio title:Fix" -> Look for Audio files which contains the title "Fix" in its title. |
46 | * |
47 | * The Query Parser recognizes a large number of properties. These property names can be looked |
48 | * up in KFileMetaData::Property::Property. The type of the file can mentioned with the property |
49 | * 'type' or 'kind'. |
50 | */ |
51 | class BALOO_CORE_EXPORT Query |
52 | { |
53 | public: |
54 | /*! |
55 | * |
56 | */ |
57 | Query(); |
58 | Query(const Query& rhs); |
59 | ~Query(); |
60 | |
61 | /*! |
62 | * Add a type to the results of the query. |
63 | * |
64 | * Every file has a higher level type such as "Audio", "Video", "Image", "Document", etc. |
65 | * |
66 | * Please note that the types are ANDed together. So searching for "Image" |
67 | * and "Video" will probably never return any results. Have a look at |
68 | * KFileMetaData::TypeInfo for a list of type names. |
69 | */ |
70 | void addType(const QString& type); |
71 | |
72 | /*! |
73 | * |
74 | */ |
75 | void addTypes(const QStringList& typeList); |
76 | |
77 | /*! |
78 | * |
79 | */ |
80 | void setType(const QString& type); |
81 | |
82 | /*! |
83 | * |
84 | */ |
85 | void setTypes(const QStringList& types); |
86 | |
87 | /*! |
88 | * |
89 | */ |
90 | QStringList types() const; |
91 | |
92 | /*! |
93 | * Set some text which should be used to search for Items. This |
94 | * contain a single word or an entire sentence. |
95 | */ |
96 | void setSearchString(const QString& str); |
97 | |
98 | /*! |
99 | * |
100 | */ |
101 | QString searchString() const; |
102 | |
103 | /*! |
104 | * Only a maximum of \a limit results will be returned. |
105 | * By default the value is -1 |
106 | */ |
107 | void setLimit(uint limit); |
108 | |
109 | /*! |
110 | * |
111 | */ |
112 | uint limit() const; |
113 | |
114 | /*! |
115 | * |
116 | */ |
117 | void setOffset(uint offset); |
118 | |
119 | /*! |
120 | * |
121 | */ |
122 | uint offset() const; |
123 | |
124 | /*! |
125 | * Filter the results in the specified date range. |
126 | * |
127 | * The year/month/day may be set to 0 in order to ignore it. |
128 | */ |
129 | void setDateFilter(int year, int month = 0, int day = 0); |
130 | |
131 | /*! |
132 | * |
133 | */ |
134 | int yearFilter() const; |
135 | |
136 | /*! |
137 | * |
138 | */ |
139 | int monthFilter() const; |
140 | |
141 | /*! |
142 | * |
143 | */ |
144 | int dayFilter() const; |
145 | |
146 | /*! |
147 | * \value SortNone The results are returned in the most efficient order. They can be returned in any order. |
148 | * \value SortAuto The results are returned in the order Baloo decides should be ideal. This criteria is based on the mtime of the file. This is the default |
149 | * sorting mechanism. |
150 | */ |
151 | enum SortingOption { |
152 | SortNone, |
153 | SortAuto, |
154 | }; |
155 | |
156 | /*! |
157 | * |
158 | */ |
159 | void setSortingOption(SortingOption option); |
160 | |
161 | /*! |
162 | * |
163 | */ |
164 | SortingOption sortingOption() const; |
165 | |
166 | /*! |
167 | * Only files in this folder will be returned |
168 | */ |
169 | void setIncludeFolder(const QString& folder); |
170 | |
171 | /*! |
172 | * |
173 | */ |
174 | QString includeFolder() const; |
175 | |
176 | /*! |
177 | * |
178 | */ |
179 | ResultIterator exec(); |
180 | |
181 | /*! |
182 | * |
183 | */ |
184 | QByteArray toJSON(); |
185 | |
186 | /*! |
187 | * |
188 | */ |
189 | static Query fromJSON(const QByteArray& arr); |
190 | |
191 | /*! |
192 | * |
193 | */ |
194 | QUrl toSearchUrl(const QString& title = QString()); |
195 | |
196 | /*! |
197 | * |
198 | */ |
199 | static Query fromSearchUrl(const QUrl& url); |
200 | |
201 | /*! |
202 | * |
203 | */ |
204 | static QString titleFromQueryUrl(const QUrl& url); |
205 | |
206 | bool operator == (const Query& rhs) const; |
207 | bool operator != (const Query& rhs) const; |
208 | |
209 | Query& operator=(const Query& rhs); |
210 | |
211 | private: |
212 | class Private; |
213 | std::unique_ptr<Private> const d; |
214 | }; |
215 | |
216 | } |
217 | #endif // BALOO_QUERY_H |
218 | |