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
18namespace 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 */
51class BALOO_CORE_EXPORT Query
52{
53public:
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
211private:
212 class Private;
213 std::unique_ptr<Private> const d;
214};
215
216}
217#endif // BALOO_QUERY_H
218

source code of baloo/src/lib/query.h