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 Query query.h <Baloo/Query>
22 *
23 * The Query class is the central class to query to search for files from the Index.
24 *
25 * This class has an inbuilt parser which recognizes words along with AND / OR and parenthesis
26 * and specific properties. This can be used with the setSearchString method
27 *
28 * @example -
29 * "Fire" -> Looks for all files which contain the word "Fire"
30 *
31 * @example -
32 * "Fire OR water" -> Looks for files which contain either "Fire" or "Water". The capitalization
33 * of the words doesn't matter as that will be ignored internally. However, OR and AND have to
34 * be in upper case.
35 *
36 * @example -
37 * "artist:Coldplay" -> Look for any files with the artist "Coldplay"
38 *
39 * @example -
40 * "artist:(Coldplay OR Maroon5) power" -> Look for files with the artist Coldplay or Maroon5 and
41 * the word "power"
42 *
43 * @example -
44 * "artist:'Noah and the Whale'" -> Look for files with the artist "Noah and the Whale"
45 *
46 * @example -
47 * "type:Audio title:Fix" -> Look for Audio files which contains the title "Fix" in its title.
48 *
49 * The Query Parser recognizes a large number of properties. These property names can be looked
50 * up in KFileMetaData::Property::Property. The type of the file can mentioned with the property
51 * 'type' or 'kind'.
52 */
53class BALOO_CORE_EXPORT Query
54{
55public:
56 Query();
57 Query(const Query& rhs);
58 ~Query();
59
60 /**
61 * Add a type to the results of the query.
62 *
63 * Every file has a higher level type such as "Audio", "Video", "Image", "Document", etc.
64 *
65 * Please note that the types are ANDed together. So searching for "Image"
66 * and "Video" will probably never return any results. Have a look at
67 * KFileMetaData::TypeInfo for a list of type names.
68 */
69 void addType(const QString& type);
70 void addTypes(const QStringList& typeList);
71 void setType(const QString& type);
72 void setTypes(const QStringList& types);
73
74 QStringList types() const;
75
76 /**
77 * Set some text which should be used to search for Items. This
78 * contain a single word or an entire sentence.
79 */
80 void setSearchString(const QString& str);
81 QString searchString() const;
82
83 /**
84 * Only a maximum of \p limit results will be returned.
85 * By default the value is -1
86 */
87 void setLimit(uint limit);
88 uint limit() const;
89
90 void setOffset(uint offset);
91 uint offset() const;
92
93 /**
94 * Filter the results in the specified date range.
95 *
96 * The year/month/day may be set to 0 in order to ignore it.
97 */
98 void setDateFilter(int year, int month = 0, int day = 0);
99
100 int yearFilter() const;
101 int monthFilter() const;
102 int dayFilter() const;
103
104 enum SortingOption {
105 /**
106 * The results are returned in the most efficient order. They can
107 * be returned in any order.
108 */
109 SortNone,
110
111 /**
112 * The results are returned in the order Baloo decides
113 * should be ideal. This criteria is based on the mtime of the
114 * file.
115 *
116 * This is the default sorting mechanism.
117 */
118 SortAuto,
119 };
120
121 void setSortingOption(SortingOption option);
122 SortingOption sortingOption() const;
123
124 /**
125 * Only files in this folder will be returned
126 */
127 void setIncludeFolder(const QString& folder);
128 QString includeFolder() const;
129
130 ResultIterator exec();
131
132 QByteArray toJSON();
133 static Query fromJSON(const QByteArray& arr);
134
135 QUrl toSearchUrl(const QString& title = QString());
136 static Query fromSearchUrl(const QUrl& url);
137 static QString titleFromQueryUrl(const QUrl& url);
138
139 bool operator == (const Query& rhs) const;
140 bool operator != (const Query& rhs) const;
141
142 Query& operator=(const Query& rhs);
143
144private:
145 class Private;
146 std::unique_ptr<Private> const d;
147};
148
149}
150#endif // BALOO_QUERY_H
151

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