src/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 <dolphinview.h>
  24 #include <kurl.h>
  25 #include <QtCore/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 DolphinController 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 tree 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 destPath  Path of the destination.
  91      * @param event     Drop event
  92      */
  93     void indicateDroppedUrls(const KFileItem& destItem,
  94                              const KUrl& destPath,
  95                              QDropEvent* event);
  96
  97     /**
  98      * Informs the DolphinView about a sorting change done inside
  99      * the view mode implementation.
 100      */
 101     void indicateSortingChange(DolphinView::Sorting sorting);
 102
 103     /**
 104      * Informs the DolphinView about a sort order change done inside
 105      * the view mode implementation.
 106      */
 107     void indicateSortOrderChange(Qt::SortOrder order);
 108
 109     /**
 110      * Informs the DolphinView about a change between separate sorting
 111      * (with folders first) and mixed sorting of files and folders done inside
 112      * the view mode implementation.
 113      */
 114     void indicateSortFoldersFirstChange(bool foldersFirst);
 115
 116     /**
 117      * Informs the DolphinView about an additional information change
 118      * done inside the view mode implementation.
 119      */
 120     void indicateAdditionalInfoChange(const KFileItemDelegate::InformationList& info);
 121
 122     /**
 123      * Sets the available version control actions. Is called by the view
 124      * mode implementation as soon as the DolphinView has requested them by the signal
 125      * requestVersionControlActions().
 126      */
 127     void setVersionControlActions(QList<QAction*> actions);
 128
 129     /**
 130      * Emits the signal requestVersionControlActions(). The view mode implementation
 131      * listens to the signal and will invoke a DolphinViewController::setVersionControlActions()
 132      * and the result will be returned.
 133      */
 134     QList<QAction*> versionControlActions(const KFileItemList& items);
 135
 136     /**
 137      * Must be be invoked in each view mode implementation whenever a key has been
 138      * pressed. If the selection model of \a view is not empty and
 139      * the return key has been pressed, the selected items will get triggered.
 140      */
 141     void handleKeyPressEvent(QKeyEvent* event);
 142
 143     /**
 144      * Replaces the URL of the DolphinView  with the content
 145      * of the clipboard as URL. If the clipboard contains no text,
 146      * nothing will be done.
 147      */
 148     void replaceUrlByClipboard();
 149
 150     /**
 151      * Requests the view mode implementation to hide tooltips.
 152      */
 153     void requestToolTipHiding();
 154
 155     /**
 156      * Emits the signal itemTriggered() for the item \a item.
 157      * The method can be used by the view mode implementations to
 158      * trigger an item directly without mouse interaction.
 159      * If the item triggering is done by the mouse, it is recommended
 160      * to use DolphinViewController::triggerItem(), as this will check
 161      * the used mouse buttons to execute the correct action.
 162      */
 163     void emitItemTriggered(const KFileItem& item);
 164
 165     /**
 166      * Returns the file item for the proxy index \a index of the DolphinView.
 167      */
 168     KFileItem itemForIndex(const QModelIndex& index) const;
 169
 170 public slots:
 171     /**
 172      * Emits the signal itemTriggered() if the file item for the index \a index
 173      * is not null and the left mouse button has been pressed. If the item is
 174      * null, the signal itemEntered() is emitted.
 175      * The method should be invoked by the view mode implementations whenever the
 176      * user has triggered an item with the mouse (see
 177      * QAbstractItemView::clicked() or QAbstractItemView::doubleClicked()).
 178      */
 179     void triggerItem(const QModelIndex& index);
 180
 181     /**
 182      * Emits the signal tabRequested(), if the file item for the index \a index
 183      * represents a directory and when the middle mouse button has been pressed.
 184      */
 185     void requestTab(const QModelIndex& index);
 186
 187     /**
 188      * Emits the signal itemEntered() if the file item for the index \a index
 189      * is not null. The method should be invoked by the view mode implementation
 190      * whenever the mouse cursor is above an item.
 191      */
 192     void emitItemEntered(const QModelIndex& index);
 193
 194     /**
 195      * Emits the signal viewportEntered(). The method should be invoked by
 196      * the view mode implementation whenever the mouse cursor is above the viewport.
 197      */
 198     void emitViewportEntered();
 199
 200 signals:
 201     void urlChangeRequested(const KUrl& url);
 202
 203     /**
 204      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 205      * @param pos           Position relative to the view widget where the
 206      *                      context menu should be opened. It is recommended
 207      *                      to get the corresponding model index from
 208      *                      this position.
 209      * @param customActions List of actions that is added to the context menu when
 210      *                      the menu is opened above the viewport.
 211      */
 212     void requestContextMenu(const QPoint& pos, QList<QAction*> customActions);
 213
 214     /**
 215      * Is emitted if the view has been activated by e. g. a mouse click.
 216      */
 217     void activated();
 218
 219     /**
 220      * Is emitted if URLs have been dropped to the destination
 221      * path \a destPath. If the URLs have been dropped above an item of
 222      * the destination path, the item is indicated by \a destItem
 223      * (can be null, see KFileItem::isNull()).
 224      */
 225     void urlsDropped(const KFileItem& destItem,
 226                      const KUrl& destPath,
 227                      QDropEvent* event);
 228
 229     /**
 230      * Is emitted if the sorting has been changed to \a sorting by
 231      * the view mode implementation (see indicateSortingChanged().
 232      * The DolphinView connects to
 233      * this signal to update its menu action.
 234      */
 235     void sortingChanged(DolphinView::Sorting sorting);
 236
 237     /**
 238      * Is emitted if the sort order has been changed to \a order
 239      * by the view mode implementation (see indicateSortOrderChanged().
 240      * The DolphinView connects
 241      * to this signal to update its menu actions.
 242      */
 243     void sortOrderChanged(Qt::SortOrder order);
 244
 245     /**
 246      * Is emitted if 'sort folders first' has been changed to \a foldersFirst
 247      * by the view mode implementation (see indicateSortOrderChanged().
 248      * The DolphinView connects
 249      * to this signal to update its menu actions.
 250      */
 251     void sortFoldersFirstChanged(bool foldersFirst);
 252
 253     /**
 254      * Is emitted if the additional info has been changed to \a info
 255      * by the view mode implementation. The DolphinView connects
 256      * to this signal to update its menu actions.
 257      */
 258     void additionalInfoChanged(const KFileItemDelegate::InformationList& info);
 259
 260     /**
 261      * Is emitted if the item \a item should be triggered. The abstract
 262      * Dolphin view connects to this signal. If the item represents a directory,
 263      * the directory is opened. On a file the corresponding application is opened.
 264      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 265      */
 266     void itemTriggered(const KFileItem& item);
 267
 268     /**
 269      * Is emitted if the mouse cursor has entered the item
 270      * given by \a index (see emitItemEntered()).
 271      */
 272     void itemEntered(const KFileItem& item);
 273
 274     /**
 275      * Is emitted if a new tab should be opened for the URL \a url.
 276      */
 277     void tabRequested(const KUrl& url);
 278
 279     /**
 280      * Is emitted if the mouse cursor has entered
 281      * the viewport (see emitViewportEntered()).
 282      */
 283     void viewportEntered();
 284
 285     /**
 286      * Is emitted, if DolphinViewController::requestToolTipHiding() is invoked
 287      * and requests to hide all tooltips.
 288      */
 289     void hideToolTip();
 290
 291     /**
 292      * Is emitted if pending previews should be canceled (e. g. because of an URL change).
 293      */
 294     void cancelPreviews();
 295
 296     /**
 297      * Requests the view mode implementation to invoke DolphinViewController::setVersionControlActions(),
 298      * so that they can be returned with DolphinViewController::versionControlActions() for
 299      * the DolphinView.
 300      */
 301     void requestVersionControlActions(const KFileItemList& items);
 302
 303 private slots:
 304     void updateMouseButtonState();
 305
 306 private:
 307     static Qt::MouseButtons m_mouseButtons; // TODO: this is a workaround until  Qt-issue 176832 has been fixed
 308
 309     DolphinView* m_dolphinView;
 310     QAbstractItemView* m_itemView;
 311     QList<QAction*> m_versionControlActions;
 312 };
 313
 314 #endif