src/search/dolphinquery.h

   1 /*
   2     SPDX-FileCopyrightText: 2019 Ismael Asensio <isma.af@mgmail.com>
   3     SPDX-FileCopyrightText: 2025 Felix Ernst <felixernst@kde.org>
   4
   5     SPDX-License-Identifier: GPL-2.0-or-later
   6 */
   7
   8 #ifndef DOLPHINQUERY_H
   9 #define DOLPHINQUERY_H
  10
  11 #include "config-dolphin.h"
  12 #include "dolphin_export.h"
  13 #include "dolphin_searchsettings.h"
  14
  15 #include <KFileMetaData/Types>
  16
  17 #include <QString>
  18 #include <QUrl>
  19
  20 #if HAVE_BALOO
  21 namespace Baloo
  22 {
  23 class Query;
  24 }
  25 #endif
  26
  27 class DolphinQueryTest;
  28
  29 namespace Search
  30 {
  31
  32 /** Specifies which locations the user expects to be searched for matches. */
  33 enum class SearchLocations {
  34     FromHere, /// Search in m_searchUrl and its sub-folders.
  35     Everywhere, /// Search "Everywhere" as far as possible.
  36 };
  37
  38 /** Specifies if items should be added to the search results when their file names or contents matches the search term. */
  39 enum class SearchThrough {
  40     FileNames,
  41     FileContents, // This option currently also includes any searches that search both through FileContents and FileNames at once because we currently provide
  42                   // no option to toggle between only searching FileContents or FileContents & FileNames for any search tool.
  43 };
  44
  45 enum class SearchTool {
  46     Filenamesearch, // Contrary to its name, it can actually also search in file contents.
  47 #if HAVE_BALOO
  48     Baloo,
  49 #endif
  50 };
  51
  52 /** @returns whether Baloo is configured to have indexed the @p directory. */
  53 bool isIndexingEnabledIn(QUrl directory);
  54
  55 /** @returns whether Baloo is configured to index file contents. */
  56 bool isContentIndexingEnabled();
  57
  58 /** @returns whether the @p urlScheme should be considered a search scheme. */
  59 bool isSupportedSearchScheme(const QString &urlScheme);
  60
  61 /**
  62  * @brief An object that fully specifies a search configuration.
  63  *
  64  * A DolphinQuery encompasses all state information to uniquely identify a search. It describes the search term, search tool, search options, and requirements
  65  * towards results. As such it can fully contain all state information of the Search::Bar because the search bars only goal is configuring and then triggering
  66  * a search.
  67  *
  68  * The @a toUrl() method constructs a search URL from the DolphinQuery which Dolphin can open to start searching. Such a search URL can also be transformed
  69  * back into a DolphinQuery object through the DolphinQuery constructor.
  70  *
  71  * When a DolphinQuery object is constructed or changed with incompatible conditions, like asking to search with an index-based search tool in a search path
  72  * which is not indexed, DolphinQuery tries to fix itself so the final search can give meaningful results.
  73  * Another example of this would be a DolphinQuery that is restricted to only search for images, which is then changed to use a search tool which does not
  74  * allow restricting results to images. In that case the DolphinQuery object would not necessarily need to fix itself, but the exported search URL will ignore
  75  * the image restriction, and the search user interface will need to update itself to make clear that the image restriction is ignored.
  76  *
  77  * Most widgets in the search UI have a `updateState()` method that takes a DolphinQuery as an argument. These methods will update the components' state to be
  78  * in line with the DolphinQuery object's configuration.
  79  */
  80 class DolphinQuery
  81 {
  82 public:
  83     /**
  84      * @brief Automagically constructs a DolphinQuery based on the given @p url.
  85      * @param url In the most usual case @p url is considered the search path and the DolphinQuery object is initialized based on saved user preferences.
  86      *            However, if the @p url has query information encoded in itself, which is supposed to be the case if the QUrl::scheme() of the @p url is
  87      *            "baloosearch", "tags", or "filenamesearch", this constructor retrieves all the information from the @p url and initializes the DolphinQuery
  88      *            with it.
  89      * @param backupSearchPath The last non-search location the user was on.
  90      *                         A DolphinQuery object should always be fully constructible from the main @p url parameter. However, the data encoded in @url
  91      *                         might not contain any search path, for example because the constructed DolphinQuery object is supposed to search "everywhere".
  92      *                         This is fine until this DolphinQuery object is switched to search in a specific location instead. In that case, this
  93      *                         @p backupSearchPath will become the new searchPath() of this DolphinQuery.
  94      */
  95     explicit DolphinQuery(const QUrl &url, const QUrl &backupSearchPath);
  96
  97     /**
  98      * @returns a representation of this DolphinQuery as a QUrl. This QUrl can be opened in Dolphin to trigger a search that is identical to the conditions
  99      *          provided by this DolphinQuery object.
 100      */
 101     QUrl toUrl() const;
 102
 103     void setSearchLocations(SearchLocations searchLocations);
 104     inline SearchLocations searchLocations() const
 105     {
 106         return m_searchLocations;
 107     };
 108
 109     /**
 110      * Set this query to search in @p searchPath. However, if @a searchLocations() is set to "Everywhere", @p searchPath is effectively ignored because it is
 111      * assumed that searching everywhere also includes @p searchPath.
 112      */
 113     void setSearchPath(const QUrl &searchPath);
 114     /**
 115      * @returns in which specific directory this query will search if the search location is not set to "Everywhere". When searching "Everywhere" this url is
 116      *          ignored completely.
 117      */
 118     inline QUrl searchPath() const
 119     {
 120         return m_searchPath;
 121     };
 122
 123     /**
 124      * Set whether search results should match the search term with their names or contain it in their file contents.
 125      */
 126     void setSearchThrough(SearchThrough searchThrough);
 127     inline SearchThrough searchThrough() const
 128     {
 129         return m_searchThrough;
 130     };
 131
 132     /**
 133      * Set the search tool or backend that will be used to @p searchTool.
 134      */
 135     inline void setSearchTool(SearchTool searchTool)
 136     {
 137         m_searchTool = searchTool;
 138         // We do not remove any search parameters here, even if the new search tool does not support them. This is an attempt to avoid that we unnecessarily
 139         // throw away configuration data. Non-applicable search parameters will be lost when exporting this DolphinQuery to a URL,
 140         // but such an export won't happen if the changed DolphinQuery is not a valid search e.g. because the searchTerm().isEmpty() and every other search
 141         // parameter is not supported by the new search tool.
 142     };
 143     /** @returns the search tool to be used for this search. */
 144     inline SearchTool searchTool() const
 145     {
 146         return m_searchTool;
 147     };
 148
 149     /**
 150      * Sets the search text the user entered into the search field to @p searchTerm.
 151      */
 152     inline void setSearchTerm(const QString &searchTerm)
 153     {
 154         m_searchTerm = searchTerm;
 155     };
 156     /** @return the search text the user entered into the search field. */
 157     inline QString searchTerm() const
 158     {
 159         return m_searchTerm;
 160     };
 161
 162     /**
 163      * Sets the type every search result should have.
 164      */
 165     inline void setFileType(const KFileMetaData::Type::Type &fileType)
 166     {
 167         m_fileType = fileType;
 168     };
 169     /**
 170      * @return the requested file type this search will be restricted to.
 171      */
 172     inline KFileMetaData::Type::Type fileType() const
 173     {
 174         return m_fileType;
 175     };
 176
 177     /**
 178      * Sets the date since when every search result needs to have been modified.
 179      */
 180     inline void setModifiedSinceDate(const QDate &modifiedLaterThanDate)
 181     {
 182         m_modifiedSinceDate = modifiedLaterThanDate;
 183     };
 184     /**
 185      * @return the date since when every search result needs to have been modified.
 186      */
 187     inline QDate modifiedSinceDate() const
 188     {
 189         return m_modifiedSinceDate;
 190     };
 191
 192     /**
 193      * @param minimumRating the minimum rating value every search result needs to at least have to be considered a valid result of this query.
 194      *                      Values <= 0 mean no restriction. 1 is half a star, 2 one full star, etc. 10 is typically the maximum in KDE software.
 195      */
 196     inline void setMinimumRating(int minimumRating)
 197     {
 198         m_minimumRating = minimumRating;
 199     };
 200     /**
 201      * @returns the minimum rating every search result is requested to have.
 202      * @see setMinimumRating().
 203      */
 204     inline int minimumRating() const
 205     {
 206         return m_minimumRating;
 207     };
 208
 209     /**
 210      * @param requiredTags All the tags every search result is required to have.
 211      */
 212     inline void setRequiredTags(const QStringList &requiredTags)
 213     {
 214         m_requiredTags = requiredTags;
 215     };
 216     /**
 217      * @returns all the tags every search result is required to have.
 218      */
 219     inline QStringList requiredTags() const
 220     {
 221         return m_requiredTags;
 222     };
 223
 224     bool operator==(const DolphinQuery &) const = default;
 225
 226     /**
 227      * @returns a title to be used in user-facing situations to represent this DolphinQuery, such as "Query Results from 'importantFile'".
 228      */
 229     QString title() const;
 230
 231 private:
 232 #if HAVE_BALOO
 233     /** Parses a Baloo::Query to extract its separate components */
 234     void initializeFromBalooQuery(const Baloo::Query &balooQuery, const QUrl &backupSearchPath);
 235 #endif
 236
 237     /**
 238      * Switches to the user's preferred search tool if this is possible. If the preferred search tool cannot perform a search within this DolphinQuery's
 239      * conditions, a different search tool will be used instead.
 240      */
 241     void switchToPreferredSearchTool();
 242
 243 private:
 244     /** Specifies which locations will be searched for the search terms. */
 245     SearchLocations m_searchLocations = SearchSettings::location() == QLatin1String("Everywhere") ? SearchLocations::Everywhere : SearchLocations::FromHere;
 246
 247     /**
 248      * Specifies where searching will begin.
 249      * @note The value of this variable is ignored when this query is set to search "Everywhere".
 250      */
 251     QUrl m_searchPath;
 252
 253     /** Specifies whether file names, file contents, or both will be searched for the search terms. */
 254     SearchThrough m_searchThrough = SearchSettings::what() == QLatin1String("FileContents") ? SearchThrough::FileContents : SearchThrough::FileNames;
 255
 256     /** Specifies which search tool will be used for the search. */
 257 #if HAVE_BALOO
 258     SearchTool m_searchTool = SearchSettings::searchTool() == QLatin1String("Baloo") ? SearchTool::Baloo : SearchTool::Filenamesearch;
 259 #else
 260     SearchTool m_searchTool = SearchTool::Filenamesearch;
 261 #endif
 262
 263     QString m_searchTerm;
 264     /** Specifies which file type all search results should have. "Empty" means there is no restriction on file type. */
 265     KFileMetaData::Type::Type m_fileType = KFileMetaData::Type::Empty;
 266
 267     /** All search results are requested to be modified later than or equal to this date. Null or invalid dates mean no restriction. */
 268     QDate m_modifiedSinceDate;
 269
 270     /**
 271      * All search results are requested to have at least this rating.
 272      * If the minimum rating is less than or equal to 0, this variable is ignored.
 273      * 1 is generally considered half a star in KDE software, 2 a full star, etc. Generally 10 is considered the max rating i.e. 5/5 stars or a song marked as
 274      * one of your favourites in a music application. Higher values are AFAIK not used in KDE applications but other software might use a different scale.
 275      */
 276     int m_minimumRating = 0;
 277
 278     /** All the tags every search result is required to have. */
 279     QStringList m_requiredTags;
 280
 281     /**
 282      * @brief Any imported Baloo search parameters (token:value pairs) which Dolphin does not understand are stored in this list unmodified.
 283      * Dolphin only allows modifying a certain selection of search parameters, but there are more. This is a bit of an unfortunate situation because we can not
 284      * represent every single query in the user interface without creating a mess of a UI. However, we also don't want to drop these extra parameters because
 285      * that would unexpectedly modify the query.
 286      * So this variable simply stores anything we don't recognize and reproduces it when exporting to a Baloo URL.
 287      */
 288     QStringList m_unrecognizedBalooQueryStrings;
 289
 290     friend DolphinQueryTest;
 291 };
 292
 293 /**
 294  * For testing Baloo in DolphinQueryTest even if it is not indexing any locations yet.
 295  * The test mode makes sure that DolphinQuery can be set to use Baloo even if Baloo has not indexed any locations yet.
 296  */
 297 void setTestMode();
 298 }
 299
 300 #endif //DOLPHINQUERY_H