src/search/bar.h

   1 /*
   2     SPDX-FileCopyrightText: 2010 Peter Penz <peter.penz19@gmail.com>
   3     SPDX-FileCopyrightText: 2025 Felix Ernst <felixernst@kde.org>
   4
   5     SPDX-License-Identifier: GPL-2.0-or-later
   6 */
   7
   8 #ifndef SEARCHBAR_H
   9 #define SEARCHBAR_H
  10
  11 #include "animatedheightwidget.h"
  12 #include "dolphinquery.h"
  13 #include "updatablestateinterface.h"
  14
  15 #include <KMessageWidget>
  16
  17 #include <QUrl>
  18
  19 class DolphinSearchBarTest;
  20 class QHBoxLayout;
  21 class QLineEdit;
  22 class QToolButton;
  23 class QVBoxLayout;
  24
  25 namespace Search
  26 {
  27 class BarSecondRowFlowLayout;
  28 template<class Selector>
  29 class Chip;
  30 class DateSelector;
  31 class FileTypeSelector;
  32 class MinimumRatingSelector;
  33 class Popup;
  34 class TagsSelector;
  35
  36 /**
  37  * @brief User interface for searching files and folders.
  38  *
  39  * This Bar is both for configuring a new search as well as showing the search parameter of any search URL opened in Dolphin.
  40  * There are many search parameters whose availability can depend on various conditions. Those include:
  41  * - Where to search: Everywhere or below the current directory
  42  * - What to search: Filenames or content
  43  * - How to search: Which search tool to use
  44  * - etc.
  45  *
  46  * The class which defines the state of this Bar and its children is DolphinQuery.
  47  * @see DolphinQuery.
  48  */
  49 class Bar : public AnimatedHeightWidget, public UpdatableStateInterface
  50 {
  51     Q_OBJECT
  52
  53 public:
  54     /**
  55      * @brief Constructs a Search::Bar with an initial state matching @p dolphinQuery and with parent @p parent.
  56      */
  57     explicit Bar(std::shared_ptr<const DolphinQuery> dolphinQuery, QWidget *parent = nullptr);
  58
  59     /**
  60      * Returns the text that should be used as input
  61      * for searching.
  62      */
  63     QString text() const;
  64
  65     /**
  66      * Sets the current path that is used as root for searching files.
  67      * If @url is the Home dir, "From Here" is selected instead.
  68      */
  69     void setSearchPath(const QUrl &url);
  70
  71     /**
  72      * Selects the whole text of the search box.
  73      */
  74     void selectAll();
  75
  76     /**
  77      * All showing and hiding of this bar is supposed to go through this method. When hiding this bar, it emits all the necessary signals to restore the view
  78      * container to a non-search URL.
  79      * This method also aims to make sure that visibilityChanged() will be emitted no matter from where setVisible() is called. This way the "Find" action can
  80      * be properly un/checked.
  81      * @see AnimatedHeightWidget::setVisible().
  82      */
  83     void setVisible(bool visible, Animated animated);
  84
  85     /**
  86      * @returns false, when the search UI has not yet been changed to search for anything specific. For example when no search term has been entered yet.
  87      *          Otherwise returns true, for example when a search term has been entered or there is a search request for all files of a specific file type or
  88      *          with a specific modification date.
  89      */
  90     bool isSearchConfigured() const;
  91
  92     /**
  93      * @returns the title for the search that is currently configured in this bar.
  94      * @see DolphinQuery::title().
  95      */
  96     QString queryTitle() const;
  97
  98 Q_SIGNALS:
  99     /**
 100      * This signals a request for the attached view container to switch to @p url.
 101      * A URL for searching is requested when the user actively engages with this UI to trigger a search.
 102      * A non-search URL is requested when this search UI is closed and no search results should be displayed anymore.
 103      */
 104     void urlChangeRequested(const QUrl &url);
 105
 106     /**
 107      * Is emitted when the bar should receive focus. This is usually triggered by a user action that implies that this bar should no longer have focus.
 108      */
 109     void focusViewRequest();
 110
 111     /**
 112      * Requests for @p message with the given @p messageType to be shown to the user in a non-modal way.
 113      */
 114     void showMessage(const QString &message, KMessageWidget::MessageType messageType);
 115
 116     /**
 117      * Requests for a progress update to be shown to the user in a non-modal way.
 118      * @param currentlyRunningTaskTitle     The task that is currently progressing.
 119      * @param installationProgressPercent   The current percentage of completion.
 120      */
 121     void showInstallationProgress(const QString &currentlyRunningTaskTitle, int installationProgressPercent);
 122
 123     /**
 124      * Is emitted when a change of the visibility of this bar is invoked in any way. This can happen from code calling from outside this class, for example
 125      * when the user triggered a keyboard shortcut to show this bar, or from inside, for example because the close button on this bar was pressed or an Escape
 126      * key press was received.
 127      */
 128     void visibilityChanged(bool visible);
 129
 130 protected:
 131     /** Handles Escape key presses to clear the search field or close this bar. */
 132     void keyPressEvent(QKeyEvent *event) override;
 133     /** Allows moving the focus to the view with the Down arrow key. */
 134     void keyReleaseEvent(QKeyEvent *event) override;
 135
 136 private Q_SLOTS:
 137     /**
 138      * Is called when any component within this Bar emits a configurationChanged() signal.
 139      * This method is then responsible to communicate the changed search configuration to every other interested party by calling
 140      * UpdatableStateInterface::updateStateToMatch() methods and commiting the new search configuration.
 141      * @see UpdatableStateInterface::updateStateToMatch().
 142      * @see commitCurrentConfiguration().
 143      */
 144     void slotConfigurationChanged(const Search::DolphinQuery &searchConfiguration);
 145
 146     /**
 147      * Changes the m_searchConfiguration in response to the user editing the search term. If no further changes to the search term happen within a time limit,
 148      * the new search configuration will eventually be commited.
 149      * @see commitCurrentConfiguration.
 150      */
 151     void slotSearchTermEdited(const QString &text);
 152
 153     /**
 154      * Commits the current search configuration and then requests moving focus away from this bar and to the view.
 155      * @see commitCurrentConfiguration.
 156      */
 157     void slotReturnPressed();
 158
 159     /**
 160      * Translates the current m_searchConfiguration into URLs which are then emitted through the urlChangeRequested() signal.
 161      * If the current m_searchConfiguration is a valid search, a searchUrl is emitted. If it is not a valid search, i.e. when isSearchConfigured() is false,
 162      * the search path is instead emitted so the view returns to showing a normal folder instead of search results.
 163      * @see urlChangeRequested().
 164      */
 165     void commitCurrentConfiguration();
 166
 167     /** Adds the current search as a link/favorite to the Places panel. */
 168     void slotSaveSearch();
 169
 170 private:
 171     /**
 172      * This Search::Bar always represents a search configuration. This method takes a new @p dolphinQuery i.e. search configuration and updates itself and all
 173      * child widgets to match it. This way the user always knows which search parameters lead to the query results that appear in the view.
 174      * @see UpdatableStateInterface::updateStateToMatch().
 175      */
 176     void updateState(const std::shared_ptr<const DolphinQuery> &dolphinQuery) override;
 177
 178     /** @see AnimatedHeightWidget::preferredHeight() */
 179     int preferredHeight() const override;
 180
 181 private:
 182     QVBoxLayout *m_topLayout = nullptr;
 183
 184     // The widgets below are sorted by their tab order.
 185
 186     QLineEdit *m_searchTermEditor = nullptr;
 187     QAction *m_saveSearchAction = nullptr;
 188     /// The main popup of this bar that allows configuring most search parameters.
 189     Popup *m_popup = nullptr;
 190     BarSecondRowFlowLayout *m_secondRowLayout = nullptr;
 191     QToolButton *m_fromHereButton = nullptr;
 192     QToolButton *m_everywhereButton = nullptr;
 193     Chip<FileTypeSelector> *m_fileTypeSelectorChip = nullptr;
 194     Chip<DateSelector> *m_modifiedSinceDateSelectorChip = nullptr;
 195     Chip<MinimumRatingSelector> *m_minimumRatingSelectorChip = nullptr;
 196     Chip<TagsSelector> *m_requiredTagsSelectorChip = nullptr;
 197
 198     /// Starts a new search when the user has finished typing the search term.
 199     QTimer *m_startSearchTimer = nullptr;
 200
 201     friend DolphinSearchBarTest;
 202 };
 203
 204 }
 205
 206 #endif