src/views/dolphinviewcontroller.h

   1 /***************************************************************************
   2  *   Copyright (C) 2010 by Peter Penz <peter.penz@gmx.at>                  *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA            *
  18  ***************************************************************************/
  19
  20 #ifndef DOLPHINVIEWCONTROLLER_H
  21 #define DOLPHINVIEWCONTROLLER_H
  22
  23 #include <views/dolphinview.h>
  24 #include <KUrl>
  25 #include <QObject>
  26 #include <libdolphin_export.h>
  27
  28 class QAbstractItemView;
  29 class DolphinView;
  30 class KUrl;
  31 class QPoint;
  32
  33 /**
  34  * @brief Allows the view mode implementations (DolphinIconsView, DolphinDetailsView, DolphinColumnView)
  35  *        to do a limited control of the DolphinView.
  36  *
  37  * The DolphinView connects to the signals of DolphinViewController to react on changes
  38  * that have been triggered by the view mode implementations. The view mode implementations
  39  * have read access to the whole DolphinView by DolphinViewController::view(). Limited control of the
  40  * DolphinView by the view mode implementations are defined by the public DolphinViewController methods.
  41  */
  42 class LIBDOLPHINPRIVATE_EXPORT DolphinViewController : public QObject
  43 {
  44     Q_OBJECT
  45
  46 public:
  47     explicit DolphinViewController(DolphinView* dolphinView);
  48     virtual ~DolphinViewController();
  49
  50     /**
  51      * Allows read access for the view mode implementation
  52      * to the DolphinView.
  53      */
  54     const DolphinView* view() const;
  55
  56     /**
  57      * Requests the DolphinView to change the URL to \p url. The signal
  58      * urlChangeRequested will be emitted.
  59      */
  60     void requestUrlChange(const KUrl& url);
  61
  62     /**
  63      * Changes the current view mode implementation where the controller is working.
  64      * This is only necessary for views like the column view, where internally
  65      * several QAbstractItemView instances are used.
  66      */
  67     void setItemView(QAbstractItemView* view);
  68     QAbstractItemView* itemView() const;
  69
  70     /**
  71      * Requests a context menu for the position \a pos. DolphinView
  72      * takes care itself to get the selected items depending from
  73      * \a pos. It is possible to define a custom list of actions for
  74      * the context menu by \a customActions.
  75      */
  76     void triggerContextMenuRequest(const QPoint& pos,
  77                                    const QList<QAction*>& customActions = QList<QAction*>());
  78
  79     /**
  80      * Requests an activation of the DolphinView and emits the signal
  81      * activated(). This method should be invoked by the view mode implementation
  82      * if e. g. a mouse click on the view has been done.
  83      */
  84     void requestActivation();
  85
  86     /**
  87      * Indicates that URLs are dropped above a destination. The DolphinView
  88      * will start the corresponding action (copy, move, link).
  89      * @param destItem  Item of the destination (can be null, see KFileItem::isNull()).
  90      * @param event     Drop event
  91      */
  92     void indicateDroppedUrls(const KFileItem& destItem, QDropEvent* event);
  93
  94     /**
  95      * Informs the DolphinView about a sorting change done inside
  96      * the view mode implementation.
  97      */
  98     void indicateSortingChange(DolphinView::Sorting sorting);
  99
 100     /**
 101      * Informs the DolphinView about a sort order change done inside
 102      * the view mode implementation.
 103      */
 104     void indicateSortOrderChange(Qt::SortOrder order);
 105
 106     /**
 107      * Informs the DolphinView about a change between separate sorting
 108      * (with folders first) and mixed sorting of files and folders done inside
 109      * the view mode implementation.
 110      */
 111     void indicateSortFoldersFirstChange(bool foldersFirst);
 112
 113     /**
 114      * Informs the DolphinView about an additional information change
 115      * done inside the view mode implementation.
 116      */
 117     void indicateAdditionalInfoChange(const KFileItemDelegate::InformationList& info);
 118
 119     /**
 120      * Sets the available version control actions. Is called by the view
 121      * mode implementation as soon as the DolphinView has requested them by the signal
 122      * requestVersionControlActions().
 123      */
 124     void setVersionControlActions(QList<QAction*> actions);
 125
 126     /**
 127      * Emits the signal requestVersionControlActions(). The view mode implementation
 128      * listens to the signal and will invoke a DolphinViewController::setVersionControlActions()
 129      * and the result will be returned.
 130      */
 131     QList<QAction*> versionControlActions(const KFileItemList& items);
 132
 133     /**
 134      * Must be be invoked in each view mode implementation whenever a key has been
 135      * pressed. If the selection model of \a view is not empty and
 136      * the return key has been pressed, the selected items will get triggered.
 137      */
 138     void handleKeyPressEvent(QKeyEvent* event);
 139
 140     /**
 141      * Replaces the URL of the DolphinView  with the content
 142      * of the clipboard as URL. If the clipboard contains no text,
 143      * nothing will be done.
 144      */
 145     void replaceUrlByClipboard();
 146
 147     /**
 148      * Requests the view mode implementation to hide tooltips.
 149      */
 150     void requestToolTipHiding();
 151
 152     /**
 153      * Emits the signal itemTriggered() for the item \a item.
 154      * The method can be used by the view mode implementations to
 155      * trigger an item directly without mouse interaction.
 156      * If the item triggering is done by the mouse, it is recommended
 157      * to use DolphinViewController::triggerItem(), as this will check
 158      * the used mouse buttons to execute the correct action.
 159      */
 160     void emitItemTriggered(const KFileItem& item);
 161
 162     /**
 163      * Returns the file item for the proxy index \a index of the DolphinView.
 164      */
 165     KFileItem itemForIndex(const QModelIndex& index) const;
 166
 167 public slots:
 168     /**
 169      * Emits the signal itemTriggered() if the file item for the index \a index
 170      * is not null and the left mouse button has been pressed. If the item is
 171      * null, the signal itemEntered() is emitted.
 172      * The method should be invoked by the view mode implementations whenever the
 173      * user has triggered an item with the mouse (see
 174      * QAbstractItemView::clicked() or QAbstractItemView::doubleClicked()).
 175      */
 176     void triggerItem(const QModelIndex& index);
 177
 178     /**
 179      * Emits the signal tabRequested(), if the file item for the index \a index
 180      * represents a directory and when the middle mouse button has been pressed.
 181      */
 182     void requestTab(const QModelIndex& index);
 183
 184     /**
 185      * Emits the signal itemEntered() if the file item for the index \a index
 186      * is not null. The method should be invoked by the view mode implementation
 187      * whenever the mouse cursor is above an item.
 188      */
 189     void emitItemEntered(const QModelIndex& index);
 190
 191     /**
 192      * Emits the signal viewportEntered(). The method should be invoked by
 193      * the view mode implementation whenever the mouse cursor is above the viewport.
 194      */
 195     void emitViewportEntered();
 196
 197 signals:
 198     void urlChangeRequested(const KUrl& url);
 199
 200     /**
 201      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 202      * @param pos           Position relative to the view widget where the
 203      *                      context menu should be opened. It is recommended
 204      *                      to get the corresponding model index from
 205      *                      this position.
 206      * @param customActions List of actions that is added to the context menu when
 207      *                      the menu is opened above the viewport.
 208      */
 209     void requestContextMenu(const QPoint& pos, QList<QAction*> customActions);
 210
 211     /**
 212      * Is emitted if the view has been activated by e. g. a mouse click.
 213      */
 214     void activated();
 215
 216     /**
 217      * Is emitted if URLs have been dropped to the destination
 218      * path \a destPath. If the URLs have been dropped above an item of
 219      * the destination path, the item is indicated by \a destItem
 220      * (can be null, see KFileItem::isNull()).
 221      */
 222     void urlsDropped(const KFileItem& destItem,
 223                      const KUrl& destPath,
 224                      QDropEvent* event);
 225
 226     /**
 227      * Is emitted if the sorting has been changed to \a sorting by
 228      * the view mode implementation (see indicateSortingChanged().
 229      * The DolphinView connects to
 230      * this signal to update its menu action.
 231      */
 232     void sortingChanged(DolphinView::Sorting sorting);
 233
 234     /**
 235      * Is emitted if the sort order has been changed to \a order
 236      * by the view mode implementation (see indicateSortOrderChanged().
 237      * The DolphinView connects
 238      * to this signal to update its menu actions.
 239      */
 240     void sortOrderChanged(Qt::SortOrder order);
 241
 242     /**
 243      * Is emitted if 'sort folders first' has been changed to \a foldersFirst
 244      * by the view mode implementation (see indicateSortOrderChanged().
 245      * The DolphinView connects
 246      * to this signal to update its menu actions.
 247      */
 248     void sortFoldersFirstChanged(bool foldersFirst);
 249
 250     /**
 251      * Is emitted if the additional info has been changed to \a info
 252      * by the view mode implementation. The DolphinView connects
 253      * to this signal to update its menu actions.
 254      */
 255     void additionalInfoChanged(const KFileItemDelegate::InformationList& info);
 256
 257     /**
 258      * Is emitted if the item \a item should be triggered. The abstract
 259      * Dolphin view connects to this signal. If the item represents a directory,
 260      * the directory is opened. On a file the corresponding application is opened.
 261      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 262      */
 263     void itemTriggered(const KFileItem& item);
 264
 265     /**
 266      * Is emitted if the mouse cursor has entered the item
 267      * given by \a index (see emitItemEntered()).
 268      */
 269     void itemEntered(const KFileItem& item);
 270
 271     /**
 272      * Is emitted if a new tab should be opened for the URL \a url.
 273      */
 274     void tabRequested(const KUrl& url);
 275
 276     /**
 277      * Is emitted if the mouse cursor has entered
 278      * the viewport (see emitViewportEntered()).
 279      */
 280     void viewportEntered();
 281
 282     /**
 283      * Is emitted, if DolphinViewController::requestToolTipHiding() is invoked
 284      * and requests to hide all tooltips.
 285      */
 286     void hideToolTip();
 287
 288     /**
 289      * Is emitted if pending previews should be canceled (e. g. because of an URL change).
 290      */
 291     void cancelPreviews();
 292
 293     /**
 294      * Requests the view mode implementation to invoke DolphinViewController::setVersionControlActions(),
 295      * so that they can be returned with DolphinViewController::versionControlActions() for
 296      * the DolphinView.
 297      */
 298     void requestVersionControlActions(const KFileItemList& items);
 299
 300 private slots:
 301     void updateMouseButtonState();
 302
 303 private:
 304     static Qt::MouseButtons m_mouseButtons; // TODO: this is a workaround until  Qt-issue 176832 has been fixed
 305
 306     DolphinView* m_dolphinView;
 307     QAbstractItemView* m_itemView;
 308     QList<QAction*> m_versionControlActions;
 309 };
 310
 311 #endif