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 QBrush;
  32 class QPoint;
  33 class QRect;
  34 class QWidget;
  35
  36 // TODO: get rid of all the state duplications in the controller and allow read access
  37 // to the Dolphin view for all view implementations
  38
  39 /**
  40  * @brief Acts as mediator between the abstract Dolphin view and the view
  41  *        implementations.
  42  *
  43  * The abstract Dolphin view (see DolphinView) represents the parent of the controller.
  44  * The lifetime of the controller is equal to the lifetime of the Dolphin view.
  45  * The controller is passed to the current view implementation
  46  * (see DolphinIconsView, DolphinDetailsView and DolphinColumnView)
  47  * by passing it in the constructor and informing the controller about the change
  48  * of the view implementation:
  49  *
  50  * \code
  51  * QAbstractItemView* view = new DolphinIconsView(parent, controller);
  52  * controller->setItemView(view);
  53  * \endcode
  54  *
  55  * The communication of the view implementations to the abstract view is done by:
  56  * - triggerContextMenuRequest()
  57  * - requestActivation()
  58  * - triggerUrlChangeRequest()
  59  * - indicateDroppedUrls()
  60  * - indicateSortingChange()
  61  * - indicateSortOrderChanged()
  62  * - triggerItem()
  63  * - requestTab()
  64  * - handleKeyPressEvent()
  65  * - emitItemEntered()
  66  * - emitViewportEntered()
  67  * - replaceUrlByClipboard()
  68  * - hideToolTip()
  69  *
  70  * The communication of the abstract view to the view implementations is done by:
  71  * - setUrl()
  72  * - setShowHiddenFiles()
  73  * - setShowPreview()
  74  * - indicateActivationChange()
  75  * - setZoomLevel()
  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      * Changes the current item view where the controller is working. This
 102      * is only necessary for views like the tree view, where internally
 103      * several QAbstractItemView instances are used.
 104      */
 105     void setItemView(QAbstractItemView* view);
 106
 107     QAbstractItemView* itemView() const;
 108
 109     /**
 110      * Allows a view implementation to request an URL change to \a url.
 111      * The signal requestUrlChange() is emitted and the abstract Dolphin view
 112      * will assure that the URL of the Dolphin Controller will be updated
 113      * later. Invoking this method makes only sense if the view implementation
 114      * shows a hierarchy of URLs and allows to change the URL within
 115      * the view (e. g. this is the case in the column view).
 116      */
 117     void triggerUrlChangeRequest(const KUrl& url);
 118
 119     /**
 120      * Requests a context menu for the position \a pos. This method
 121      * should be invoked by the view implementation when a context
 122      * menu should be opened. The abstract Dolphin view itself
 123      * takes care itself to get the selected items depending from
 124      * \a pos. It is possible to define a custom list of actions for
 125      * the context menu by \a customActions.
 126      */
 127     void triggerContextMenuRequest(const QPoint& pos,
 128                                    const QList<QAction*>& customActions = QList<QAction*>());
 129
 130     /**
 131      * Requests an activation of the view and emits the signal
 132      * activated(). This method should be invoked by the view implementation
 133      * if e. g. a mouse click on the view has been done.
 134      * After the activation has been changed, the view implementation
 135      * might listen to the activationChanged() signal.
 136      */
 137     void requestActivation();
 138
 139     /**
 140      * Indicates that URLs are dropped above a destination. This method
 141      * should be invoked by the view implementation. The abstract Dolphin view
 142      * will start the corresponding action (copy, move, link).
 143      * @param destItem  Item of the destination (can be null, see KFileItem::isNull()).
 144      * @param destPath  Path of the destination.
 145      * @param event     Drop event
 146      */
 147     void indicateDroppedUrls(const KFileItem& destItem,
 148                              const KUrl& destPath,
 149                              QDropEvent* event);
 150
 151     /**
 152      * Informs the abstract Dolphin view about a sorting change done inside
 153      * the view implementation. This method should be invoked by the view
 154      * implementation (e. g. the details view uses this method in combination
 155      * with the details header).
 156      */
 157     void indicateSortingChange(DolphinView::Sorting sorting);
 158
 159     /**
 160      * Informs the abstract Dolphin view about a sort order change 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 indicateSortOrderChange(Qt::SortOrder order);
 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      * Tells the view implementation to zoom out by emitting the signal zoomOut()
 194      * and is invoked by the abstract Dolphin view.
 195      */
 196     void triggerZoomOut();
 197
 198     /**
 199      * Should be invoked in each view implementation whenever a key has been
 200      * pressed. If the selection model of \a view is not empty and
 201      * the return key has been pressed, the selected items will get triggered.
 202      */
 203     void handleKeyPressEvent(QKeyEvent* event);
 204
 205     /**
 206      * Replaces the URL of the abstract Dolphin view  with the content
 207      * of the clipboard as URL. If the clipboard contains no text,
 208      * nothing will be done.
 209      */
 210     void replaceUrlByClipboard();
 211
 212     /** Emits the signal hideToolTip(). */
 213     void emitHideToolTip();
 214
 215     /**
 216      * Emits the signal itemTriggered() for the item \a item.
 217      * The method can be used by the view implementations to
 218      * trigger an item directly without mouse interaction.
 219      * If the item triggering is done by the mouse, it is recommended
 220      * to use QAbstractItemView::triggerItem(), as this will check
 221      * the used mouse buttons to execute the correct action.
 222      */
 223     void emitItemTriggered(const KFileItem& item);
 224
 225     /**
 226      * Returns the file item for the proxy index \a index of the view \a view.
 227      */
 228     KFileItem itemForIndex(const QModelIndex& index) const;
 229
 230 public slots:
 231     /**
 232      * Emits the signal itemTriggered() if the file item for the index \a index
 233      * is not null and the left mouse button has been pressed. If the item is
 234      * null, the signal itemEntered() is emitted.
 235      * The method should be invoked by the view implementations whenever the
 236      * user has triggered an item with the mouse (see
 237      * QAbstractItemView::clicked() or QAbstractItemView::doubleClicked()).
 238      */
 239     void triggerItem(const QModelIndex& index);
 240
 241     /**
 242      * Emits the signal tabRequested(), if the file item for the index \a index
 243      * represents a directory and when the middle mouse button has been pressed.
 244      * The method should be invoked by the controller parent.
 245      */
 246     void requestTab(const QModelIndex& index);
 247
 248     /**
 249      * Emits the signal itemEntered() if the file item for the index \a index
 250      * is not null. The method should be invoked by the controller parent
 251      * whenever the mouse cursor is above an item.
 252      */
 253     void emitItemEntered(const QModelIndex& index);
 254
 255     /**
 256      * Emits the signal viewportEntered(). The method should be invoked by
 257      * the controller parent whenever the mouse cursor is above the viewport.
 258      */
 259     void emitViewportEntered();
 260
 261 signals:
 262     /**
 263      * Is emitted if the URL for the Dolphin controller has been changed
 264      * to \a url.
 265      */
 266     void urlChanged(const KUrl& url);
 267
 268     /**
 269      * Is emitted if the view implementation requests a changing of the current
 270      * URL to \a url (see triggerUrlChangeRequest()).
 271      */
 272     void requestUrlChange(const KUrl& url);
 273
 274     /**
 275      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 276      * The abstract Dolphin view connects to this signal and will open the context menu.
 277      * @param pos           Position relative to the view widget where the
 278      *                      context menu should be opened. It is recommended
 279      *                      to get the corresponding model index from
 280      *                      this position.
 281      * @param customActions List of actions that is added to the context menu when
 282      *                      the menu is opened above the viewport.
 283      */
 284     void requestContextMenu(const QPoint& pos, QList<QAction*> customActions);
 285
 286     /**
 287      * Is emitted if the view has been activated by e. g. a mouse click.
 288      * The abstract Dolphin view connects to this signal to know the
 289      * destination view for the menu actions.
 290      */
 291     void activated();
 292
 293     /**
 294      * Is emitted if URLs have been dropped to the destination
 295      * path \a destPath. If the URLs have been dropped above an item of
 296      * the destination path, the item is indicated by \a destItem
 297      * (can be null, see KFileItem::isNull()).
 298      */
 299     void urlsDropped(const KFileItem& destItem,
 300                      const KUrl& destPath,
 301                      QDropEvent* event);
 302
 303     /**
 304      * Is emitted if the sorting has been changed to \a sorting by
 305      * the view implementation (see indicateSortingChanged().
 306      * The abstract Dolphin view connects to
 307      * this signal to update its menu action.
 308      */
 309     void sortingChanged(DolphinView::Sorting sorting);
 310
 311     /**
 312      * Is emitted if the sort order has been changed to \a order
 313      * by the view implementation (see indicateSortOrderChanged().
 314      * The abstract Dolphin view connects
 315      * to this signal to update its menu actions.
 316      */
 317     void sortOrderChanged(Qt::SortOrder order);
 318
 319     /**
 320      * Is emitted if the additional info has been changed to \a info
 321      * by the view implementation. The abstract Dolphin view connects
 322      * to this signal to update its menu actions.
 323      */
 324     void additionalInfoChanged(const KFileItemDelegate::InformationList& info);
 325
 326     /**
 327      * Is emitted if the activation state has been changed to \a active
 328      * by the abstract Dolphin view.
 329      * The view implementation might connect to this signal if custom
 330      * updates are required in this case.
 331      */
 332     void activationChanged(bool active);
 333
 334     /**
 335      * Is emitted if the item \a item should be triggered. The abstract
 336      * Dolphin view connects to this signal. If the item represents a directory,
 337      * the directory is opened. On a file the corresponding application is opened.
 338      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 339      */
 340     void itemTriggered(const KFileItem& item);
 341
 342     /**
 343      * Is emitted if the mouse cursor has entered the item
 344      * given by \a index (see emitItemEntered()).
 345      * The abstract Dolphin view connects to this signal.
 346      */
 347     void itemEntered(const KFileItem& item);
 348
 349     /**
 350      * Is emitted if a new tab should be opened for the URL \a url.
 351      */
 352     void tabRequested(const KUrl& url);
 353
 354     /**
 355      * Is emitted if the mouse cursor has entered
 356      * the viewport (see emitViewportEntered().
 357      * The abstract Dolphin view connects to this signal.
 358      */
 359     void viewportEntered();
 360
 361     /**
 362      * Is emitted if the view should change the zoom to \a level. The view implementation
 363      * must connect to this signal if it supports zooming.
 364      */
 365     void zoomLevelChanged(int level);
 366
 367     /**
 368      * Is emitted if the abstract view should hide an open tooltip.
 369      */
 370     void hideToolTip();
 371
 372 private slots:
 373     void updateMouseButtonState();
 374
 375 private:
 376     int m_zoomLevel;
 377     static Qt::MouseButtons m_mouseButtons; // TODO: this is a workaround until  Qt-issue 176832 has been fixed
 378     KUrl m_url;
 379     DolphinView* m_dolphinView;
 380     QAbstractItemView* m_itemView;
 381 };
 382
 383 inline const DolphinView* DolphinController::dolphinView() const
 384 {
 385     return m_dolphinView;
 386 }
 387
 388 inline const KUrl& DolphinController::url() const
 389 {
 390     return m_url;
 391 }
 392
 393 inline QAbstractItemView* DolphinController::itemView() const
 394 {
 395     return m_itemView;
 396 }
 397
 398 inline int DolphinController::zoomLevel() const
 399 {
 400     return m_zoomLevel;
 401 }
 402
 403 #endif