src/dolphincontroller.h

   1 /***************************************************************************
   2  *   Copyright (C) 2006 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 DOLPHINCONTROLLER_H
  21 #define DOLPHINCONTROLLER_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 // TODO: get rid of all the state duplications in the controller and allow read access
  34 // to the Dolphin view for all view implementations
  35
  36 /**
  37  * @brief Acts as mediator between the abstract Dolphin view and the view
  38  *        implementations.
  39  *
  40  * The abstract Dolphin view (see DolphinView) represents the parent of the controller.
  41  * The lifetime of the controller is equal to the lifetime of the Dolphin view.
  42  * The controller is passed to the current view implementation
  43  * (see DolphinIconsView, DolphinDetailsView and DolphinColumnView)
  44  * by passing it in the constructor and informing the controller about the change
  45  * of the view implementation:
  46  *
  47  * \code
  48  * QAbstractItemView* view = new DolphinIconsView(parent, controller);
  49  * controller->setItemView(view);
  50  * \endcode
  51  *
  52  * The communication of the view implementations to the abstract view is done by:
  53  * - triggerContextMenuRequest()
  54  * - requestActivation()
  55  * - triggerUrlChangeRequest()
  56  * - indicateDroppedUrls()
  57  * - indicateSortingChange()
  58  * - indicateSortOrderChanged()
  59  * - indicateSortFoldersFirstChanged()
  60  * - triggerItem()
  61  * - requestTab()
  62  * - handleKeyPressEvent()
  63  * - emitItemEntered()
  64  * - emitViewportEntered()
  65  * - replaceUrlByClipboard()
  66  * - hideToolTip()
  67  * - setVersionControlActions()
  68  *
  69  * The communication of the abstract view to the view implementations is done by:
  70  * - setUrl()
  71  * - indicateActivationChange()
  72  * - setNameFilter()
  73  * - setZoomLevel()
  74  * - versionControlActions()
  75  */
  76 class LIBDOLPHINPRIVATE_EXPORT DolphinController : public QObject
  77 {
  78     Q_OBJECT
  79
  80 public:
  81     explicit DolphinController(DolphinView* dolphinView);
  82     virtual ~DolphinController();
  83
  84     /**
  85      * Allows read access for the view implementation to the abstract
  86      * Dolphin view.
  87      */
  88     const DolphinView* dolphinView() const;
  89
  90     /**
  91      * Sets the URL to \a url and emits the signal urlChanged() if
  92      * \a url is different for the current URL. This method should
  93      * be invoked by the abstract Dolphin view whenever the current
  94      * URL has been changed.
  95      */
  96     void setUrl(const KUrl& url);
  97     const KUrl& url() const;
  98
  99     /**
 100      * Sets the URL to \a url and does nothing else. Called when
 101      * a redirection happens.
 102      */
 103     void redirectToUrl(const KUrl& url);
 104
 105     /**
 106      * Changes the current item view where the controller is working. This
 107      * is only necessary for views like the tree view, where internally
 108      * several QAbstractItemView instances are used.
 109      */
 110     void setItemView(QAbstractItemView* view);
 111
 112     QAbstractItemView* itemView() const;
 113
 114     /**
 115      * Allows a view implementation to request an URL change to \a url.
 116      * The signal requestUrlChange() is emitted and the abstract Dolphin view
 117      * will assure that the URL of the Dolphin Controller will be updated
 118      * later. Invoking this method makes only sense if the view implementation
 119      * shows a hierarchy of URLs and allows to change the URL within
 120      * the view (e. g. this is the case in the column view).
 121      */
 122     void triggerUrlChangeRequest(const KUrl& url);
 123
 124     /**
 125      * Requests a context menu for the position \a pos. This method
 126      * should be invoked by the view implementation when a context
 127      * menu should be opened. The abstract Dolphin view itself
 128      * takes care itself to get the selected items depending from
 129      * \a pos. It is possible to define a custom list of actions for
 130      * the context menu by \a customActions.
 131      */
 132     void triggerContextMenuRequest(const QPoint& pos,
 133                                    const QList<QAction*>& customActions = QList<QAction*>());
 134
 135     /**
 136      * Requests an activation of the view and emits the signal
 137      * activated(). This method should be invoked by the view implementation
 138      * if e. g. a mouse click on the view has been done.
 139      * After the activation has been changed, the view implementation
 140      * might listen to the activationChanged() signal.
 141      */
 142     void requestActivation();
 143
 144     /**
 145      * Indicates that URLs are dropped above a destination. This method
 146      * should be invoked by the view implementation. The abstract Dolphin view
 147      * will start the corresponding action (copy, move, link).
 148      * @param destItem  Item of the destination (can be null, see KFileItem::isNull()).
 149      * @param destPath  Path of the destination.
 150      * @param event     Drop event
 151      */
 152     void indicateDroppedUrls(const KFileItem& destItem,
 153                              const KUrl& destPath,
 154                              QDropEvent* event);
 155
 156     /**
 157      * Informs the abstract Dolphin view about a sorting change done inside
 158      * the view implementation. This method should be invoked by the view
 159      * implementation (e. g. the details view uses this method in combination
 160      * with the details header).
 161      */
 162     void indicateSortingChange(DolphinView::Sorting sorting);
 163
 164     /**
 165      * Informs the abstract Dolphin view about a sort order change done inside
 166      * the view implementation. This method should be invoked by the view
 167      * implementation (e. g. the details view uses this method in combination
 168      * with the details header).
 169      */
 170     void indicateSortOrderChange(Qt::SortOrder order);
 171
 172     /**
 173      * Informs the abstract Dolphin view about a change between separate sorting
 174      * (with folders first) and mixed sorting of files and folders done inside
 175      * the view implementation. This method should be invoked by the view
 176      * implementation (e. g. the details view uses this method in combination
 177      * with the details header).
 178      */
 179     void indicateSortFoldersFirstChange(bool foldersFirst);
 180
 181     /**
 182      * Informs the abstract Dolphin view about an additional information change
 183      * done inside the view implementation. This method should be invoked by the
 184      * view implementation (e. g. the details view uses this method in combination
 185      * with the details header).
 186      */
 187     void indicateAdditionalInfoChange(const KFileItemDelegate::InformationList& info);
 188
 189     /**
 190      * Informs the view implementation about a change of the activation
 191      * state and is invoked by the abstract Dolphin view. The signal
 192      * activationChanged() is emitted.
 193      */
 194     void indicateActivationChange(bool active);
 195
 196     /**
 197      * Sets the zoom level to \a level and emits the signal zoomLevelChanged().
 198      * It must be assured that the used level is inside the range
 199      * DolphinController::zoomLevelMinimum() and
 200      * DolphinController::zoomLevelMaximum().
 201      * Is invoked by the abstract Dolphin view.
 202      */
 203     void setZoomLevel(int level);
 204     int zoomLevel() const;
 205
 206     /**
 207      * Sets the available version control actions. Is called by the view
 208      * implementation as soon as the controller has send the signal
 209      * requestVersionControlActions().
 210      */
 211     void setVersionControlActions(QList<QAction*> actions);
 212
 213     /**
 214      * Returns the version control actions that are provided for the items \p items.
 215      * Is called by the abstract Dolphin view to show the version control actions
 216      * inside the context menu.
 217      */
 218     QList<QAction*> versionControlActions(const KFileItemList& items);
 219
 220     /**
 221      * Sets the name filter to \a and emits the signal nameFilterChanged().
 222      */
 223     void setNameFilter(const QString& nameFilter);
 224     QString nameFilter() const;
 225
 226     /**
 227      * Tells the view implementation to zoom out by emitting the signal zoomOut()
 228      * and is invoked by the abstract Dolphin view.
 229      */
 230     void triggerZoomOut();
 231
 232     /**
 233      * Should be invoked in each view implementation whenever a key has been
 234      * pressed. If the selection model of \a view is not empty and
 235      * the return key has been pressed, the selected items will get triggered.
 236      */
 237     void handleKeyPressEvent(QKeyEvent* event);
 238
 239     /**
 240      * Replaces the URL of the abstract Dolphin view  with the content
 241      * of the clipboard as URL. If the clipboard contains no text,
 242      * nothing will be done.
 243      */
 244     void replaceUrlByClipboard();
 245
 246     /** Emits the signal hideToolTip(). */
 247     void emitHideToolTip();
 248
 249     /**
 250      * Emits the signal itemTriggered() for the item \a item.
 251      * The method can be used by the view implementations to
 252      * trigger an item directly without mouse interaction.
 253      * If the item triggering is done by the mouse, it is recommended
 254      * to use QAbstractItemView::triggerItem(), as this will check
 255      * the used mouse buttons to execute the correct action.
 256      */
 257     void emitItemTriggered(const KFileItem& item);
 258
 259     /**
 260      * Returns the file item for the proxy index \a index of the view \a view.
 261      */
 262     KFileItem itemForIndex(const QModelIndex& index) const;
 263
 264 public slots:
 265     /**
 266      * Emits the signal itemTriggered() if the file item for the index \a index
 267      * is not null and the left mouse button has been pressed. If the item is
 268      * null, the signal itemEntered() is emitted.
 269      * The method should be invoked by the view implementations whenever the
 270      * user has triggered an item with the mouse (see
 271      * QAbstractItemView::clicked() or QAbstractItemView::doubleClicked()).
 272      */
 273     void triggerItem(const QModelIndex& index);
 274
 275     /**
 276      * Emits the signal tabRequested(), if the file item for the index \a index
 277      * represents a directory and when the middle mouse button has been pressed.
 278      * The method should be invoked by the view implementation.
 279      */
 280     void requestTab(const QModelIndex& index);
 281
 282     /**
 283      * Emits the signal itemEntered() if the file item for the index \a index
 284      * is not null. The method should be invoked by the view implementation
 285      * whenever the mouse cursor is above an item.
 286      */
 287     void emitItemEntered(const QModelIndex& index);
 288
 289     /**
 290      * Emits the signal viewportEntered(). The method should be invoked by
 291      * the view implementation whenever the mouse cursor is above the viewport.
 292      */
 293     void emitViewportEntered();
 294
 295 signals:
 296     /**
 297      * Is emitted if the URL for the Dolphin controller has been changed
 298      * to \a url.
 299      */
 300     void urlChanged(const KUrl& url);
 301
 302     /**
 303      * Is emitted if the view implementation requests a changing of the current
 304      * URL to \a url (see triggerUrlChangeRequest()).
 305      */
 306     void requestUrlChange(const KUrl& url);
 307
 308     /**
 309      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 310      * The abstract Dolphin view connects to this signal and will open the context menu.
 311      * @param pos           Position relative to the view widget where the
 312      *                      context menu should be opened. It is recommended
 313      *                      to get the corresponding model index from
 314      *                      this position.
 315      * @param customActions List of actions that is added to the context menu when
 316      *                      the menu is opened above the viewport.
 317      */
 318     void requestContextMenu(const QPoint& pos, QList<QAction*> customActions);
 319
 320     /**
 321      * Is emitted if the view has been activated by e. g. a mouse click.
 322      * The abstract Dolphin view connects to this signal to know the
 323      * destination view for the menu actions.
 324      */
 325     void activated();
 326
 327     /**
 328      * Is emitted if URLs have been dropped to the destination
 329      * path \a destPath. If the URLs have been dropped above an item of
 330      * the destination path, the item is indicated by \a destItem
 331      * (can be null, see KFileItem::isNull()).
 332      */
 333     void urlsDropped(const KFileItem& destItem,
 334                      const KUrl& destPath,
 335                      QDropEvent* event);
 336
 337     /**
 338      * Is emitted if the sorting has been changed to \a sorting by
 339      * the view implementation (see indicateSortingChanged().
 340      * The abstract Dolphin view connects to
 341      * this signal to update its menu action.
 342      */
 343     void sortingChanged(DolphinView::Sorting sorting);
 344
 345     /**
 346      * Is emitted if the sort order has been changed to \a order
 347      * by the view implementation (see indicateSortOrderChanged().
 348      * The abstract Dolphin view connects
 349      * to this signal to update its menu actions.
 350      */
 351     void sortOrderChanged(Qt::SortOrder order);
 352
 353     /**
 354      * Is emitted if 'sort folders first' has been changed to \a foldersFirst
 355      * by the view implementation (see indicateSortOrderChanged().
 356      * The abstract Dolphin view connects
 357      * to this signal to update its menu actions.
 358      */
 359     void sortFoldersFirstChanged(bool foldersFirst);
 360
 361     /**
 362      * Is emitted if the additional info has been changed to \a info
 363      * by the view implementation. The abstract Dolphin view connects
 364      * to this signal to update its menu actions.
 365      */
 366     void additionalInfoChanged(const KFileItemDelegate::InformationList& info);
 367
 368     /**
 369      * Is emitted if the activation state has been changed to \a active
 370      * by the abstract Dolphin view.
 371      * The view implementation might connect to this signal if custom
 372      * updates are required in this case.
 373      */
 374     void activationChanged(bool active);
 375
 376     /**
 377      * Is emitted if the item \a item should be triggered. The abstract
 378      * Dolphin view connects to this signal. If the item represents a directory,
 379      * the directory is opened. On a file the corresponding application is opened.
 380      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 381      */
 382     void itemTriggered(const KFileItem& item);
 383
 384     /**
 385      * Is emitted if the mouse cursor has entered the item
 386      * given by \a index (see emitItemEntered()).
 387      * The abstract Dolphin view connects to this signal.
 388      */
 389     void itemEntered(const KFileItem& item);
 390
 391     /**
 392      * Is emitted if a new tab should be opened for the URL \a url.
 393      */
 394     void tabRequested(const KUrl& url);
 395
 396     /**
 397      * Is emitted if the mouse cursor has entered
 398      * the viewport (see emitViewportEntered()).
 399      * The abstract Dolphin view connects to this signal.
 400      */
 401     void viewportEntered();
 402
 403     /**
 404      * Is emitted if the view should respect the name filter \a nameFilter. The view
 405      * implementation must connect to this signal if it supports name filters.
 406      */
 407     void nameFilterChanged(const QString& nameFilter);
 408
 409     /**
 410      * Is emitted if the view should change the zoom to \a level. The view implementation
 411      * must connect to this signal if it supports zooming.
 412      */
 413     void zoomLevelChanged(int level);
 414
 415     /**
 416      * Is emitted if the abstract view should hide an open tooltip.
 417      */
 418     void hideToolTip();
 419
 420     /**
 421      * Is emitted if pending previews should be canceled (e. g. because of an URL change).
 422      */
 423     void cancelPreviews();
 424
 425     /**
 426      * Requests the view implementation to invoke DolphinController::setVersionControlActions(),
 427      * so that they can be returned with DolphinController::versionControlActions() for
 428      * the abstract Dolphin view.
 429      */
 430     void requestVersionControlActions(const KFileItemList& items);
 431
 432 private slots:
 433     void updateMouseButtonState();
 434
 435 private:
 436     int m_zoomLevel;
 437     QString m_nameFilter;
 438     static Qt::MouseButtons m_mouseButtons; // TODO: this is a workaround until  Qt-issue 176832 has been fixed
 439     KUrl m_url;
 440     DolphinView* m_dolphinView;
 441     QAbstractItemView* m_itemView;
 442     QList<QAction*> m_versionControlActions;
 443 };
 444
 445 inline const DolphinView* DolphinController::dolphinView() const
 446 {
 447     return m_dolphinView;
 448 }
 449
 450 inline const KUrl& DolphinController::url() const
 451 {
 452     return m_url;
 453 }
 454
 455 inline QAbstractItemView* DolphinController::itemView() const
 456 {
 457     return m_itemView;
 458 }
 459
 460 inline int DolphinController::zoomLevel() const
 461 {
 462     return m_zoomLevel;
 463 }
 464
 465 #endif