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