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