src/dolphinnavigatorswidgetaction.h

   1 /*
   2     This file is part of the KDE project
   3     SPDX-FileCopyrightText: 2020 Felix Ernst <felixernst@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 DOLPHINNAVIGATORSWIDGETACTION_H
   9 #define DOLPHINNAVIGATORSWIDGETACTION_H
  10
  11 #include "dolphinurlnavigator.h"
  12
  13 #include <QPointer>
  14 #include <QSplitter>
  15 #include <QTimer>
  16 #include <QWidgetAction>
  17
  18 #include <memory>
  19
  20 class KXmlGuiWindow;
  21 class QPushButton;
  22
  23 /**
  24  * @brief QWidgetAction that allows to use DolphinUrlNavigators in a toolbar.
  25  *
  26  * This class is mainly a container that manages up to two DolphinUrlNavigator objects so they
  27  * can be added to a toolbar. It also deals with alignment.
  28  *
  29  * The structure of the defaultWidget() of this QWidgetAction is as follows:
  30  * - A QSplitter manages up to two sides which each correspond to one DolphinViewContainer.
  31  *      The secondary side only exists for split view and is created by
  32  *      createSecondaryUrlNavigator() when necessary.
  33  * - Each side is a QWidget which I call NavigatorWidget with a QHBoxLayout.
  34  * - Each NavigatorWidget consists an UrlNavigator, an emptyTrashButton, a
  35  *   networkFolderButton, and spacing.
  36  * - Only the primary navigatorWidget has leading spacing. Both have trailing spacing.
  37  *      The spacing is there to align the UrlNavigator with its DolphinViewContainer.
  38  */
  39 class DolphinNavigatorsWidgetAction : public QWidgetAction
  40 {
  41     Q_OBJECT
  42
  43 public:
  44     DolphinNavigatorsWidgetAction(QWidget *parent = nullptr);
  45
  46     /**
  47      * Adjusts the width of the spacings used to align the UrlNavigators with ViewContainers.
  48      * This can only work nicely if up-to-date geometry of ViewContainers is cached so
  49      * followViewContainersGeometry() has to have been called at least once before.
  50      */
  51     void adjustSpacing();
  52
  53     /**
  54      * The secondary UrlNavigator is only created on-demand. Such an action is not necessary
  55      * for the primary UrlNavigator which is created preemptively.
  56      *
  57      * This method should preferably only be called when:
  58      * - Split view is activated in the active tab
  59      * OR
  60      * - A switch to a tab that is already in split view mode is occurring
  61      */
  62     void createSecondaryUrlNavigator();
  63
  64     /**
  65      * Notify this widget of changes in geometry of the ViewContainers it tries to be
  66      * aligned with.
  67      */
  68     void followViewContainersGeometry(QWidget *primaryViewContainer, QWidget *secondaryViewContainer = nullptr);
  69
  70     bool isInToolbar() const;
  71
  72     /**
  73      * @return the primary UrlNavigator.
  74      */
  75     DolphinUrlNavigator *primaryUrlNavigator() const;
  76     /**
  77      * @return the secondary UrlNavigator and nullptr if it doesn't exist.
  78      */
  79     DolphinUrlNavigator *secondaryUrlNavigator() const;
  80
  81     /**
  82      * Change the visibility of the secondary UrlNavigator including spacing.
  83      * @param visible Setting this to false will completely hide the secondary side of this
  84      *                WidgetAction's QSplitter making the QSplitter effectively disappear.
  85      */
  86     void setSecondaryNavigatorVisible(bool visible);
  87
  88     /**
  89      * Sets the background cosmetic of the location bar(s) visible or hidden.
  90      * In frameless designs it's better to hide the background.
  91      * @param enabled True for showing background cosmetic, false for hiding it.
  92      */
  93     void setBackgroundEnabled(bool enabled);
  94
  95 protected:
  96     /**
  97      * There should always ever be one navigatorsWidget for this action so
  98      * this method always returns the same widget and reparents it.
  99      * You normally don't have to use this method directly because
 100      * QWidgetAction::requestWidget() is used to obtain the navigatorsWidget
 101      * and to steal it from wherever it was prior.
 102      * @param parent the new parent of the navigatorsWidget.
 103      */
 104     QWidget *createWidget(QWidget *parent) override;
 105
 106     /** @see QWidgetAction::deleteWidget() */
 107     void deleteWidget(QWidget *widget) override;
 108
 109 private:
 110     /**
 111      * In Left-to-right languages the Primary side will be the left one.
 112      */
 113     enum Side { Primary, Secondary };
 114     /**
 115      * Used to create the navigatorWidgets for both sides of the QSplitter.
 116      */
 117     QWidget *createNavigatorWidget(Side side) const;
 118
 119     /**
 120      * Used to retrieve the emptyTrashButtons for the navigatorWidgets on both sides.
 121      */
 122     QPushButton *emptyTrashButton(Side side);
 123
 124     /**
 125      * Creates a new empty trash button.
 126      * @param urlNavigator Only when this UrlNavigator shows the trash directory
 127      *                     will the button be visible.
 128      * @param parent       Aside from the usual QObject deletion mechanisms,
 129      *                     this parameter influences the positioning of dialog windows
 130      *                     pertaining to this trash button.
 131      */
 132     QPushButton *newEmptyTrashButton(const DolphinUrlNavigator *urlNavigator, QWidget *parent) const;
 133
 134     /**
 135      * Used to retrieve the networkFolderButtons for the navigatorWidgets on
 136      * both sides.
 137      */
 138     QPushButton *networkFolderButton(Side side);
 139
 140     /**
 141      * Creates a new add "network folder" button.
 142      * @param urlNavigator Only when this UrlNavigator shows the remote directory
 143      *                     will the button be visible.
 144      * @param parent       The object that should be the button's parent.
 145      */
 146     QPushButton *newNetworkFolderButton(const DolphinUrlNavigator *urlNavigator, QWidget *parent) const;
 147
 148     enum Position { Leading, Trailing };
 149     /**
 150      * Used to retrieve both the leading and trailing spacing for the navigatorWidgets
 151      * on both sides. A secondary leading spacing does not exist.
 152      */
 153     QWidget *spacing(Side side, Position position) const;
 154
 155     /**
 156      * Sets this action's text depending on the amount of visible UrlNavigators.
 157      */
 158     void updateText();
 159
 160     /**
 161      * The defaultWidget() of this QWidgetAction.
 162      */
 163     std::unique_ptr<QSplitter> m_splitter;
 164
 165     /**
 166      * adjustSpacing() has to be called slightly later than when urlChanged is emitted.
 167      * This timer bridges that time.
 168      */
 169     std::unique_ptr<QTimer> m_adjustSpacingTimer;
 170
 171     /**
 172      * Extracts the geometry information needed by adjustSpacing() from
 173      * ViewContainers. They are also monitored for size changes which
 174      * will lead to adjustSpacing() calls.
 175      */
 176     class ViewGeometriesHelper : public QObject
 177     {
 178     public:
 179         /**
 180          * @param navigatorsWidget       The QWidget of the navigatorsWidgetAction.
 181          * @param navigatorsWidgetAction is only used to call adjustSpacing() whenever that is
 182          *                               deemed necessary.
 183          */
 184         ViewGeometriesHelper(QWidget *navigatorsWidget, DolphinNavigatorsWidgetAction *navigatorsWidgetAction);
 185
 186         /**
 187          * Calls m_navigatorsWidgetAction::adjustSpacing() when a watched object is resized.
 188          */
 189         bool eventFilter(QObject *watched, QEvent *event) override;
 190
 191         /**
 192          * Sets the ViewContainers whose geometry is obtained when viewGeometries() is called.
 193          */
 194         void setViewContainers(QWidget *primaryViewContainer, QWidget *secondaryViewContainer = nullptr);
 195
 196         struct Geometries {
 197             int globalXOfNavigatorsWidget;
 198             int globalXOfPrimary;
 199             int widthOfPrimary;
 200             int globalXOfSecondary;
 201             int widthOfSecondary;
 202         };
 203         /**
 204          * @return a Geometries struct that contains values adjustSpacing() requires.
 205          */
 206         Geometries viewGeometries();
 207
 208     private:
 209         QWidget *m_navigatorsWidget;
 210         /** Is only used to call adjustSpacing() whenever that is deemed necessary. */
 211         DolphinNavigatorsWidgetAction *m_navigatorsWidgetAction;
 212
 213         QPointer<QWidget> m_primaryViewContainer;
 214         QPointer<QWidget> m_secondaryViewContainer;
 215     };
 216
 217     ViewGeometriesHelper m_viewGeometriesHelper;
 218
 219     /**
 220      * Used to check if the window has been resized.
 221      * @see ViewGeometriesHelper::eventFilter() for why this is needed.
 222      */
 223     int m_previousWindowWidth = -1;
 224 };
 225
 226 #endif // DOLPHINNAVIGATORSWIDGETACTION_H