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  * - handleKeyPressEvent()
  64  * - emitItemEntered()
  65  * - emitViewportEntered()
  66  * - replaceUrlByClipboard()
  67  *
  68  * The communication of the abstract view to the view implementations is done by:
  69  * - setUrl()
  70  * - setShowHiddenFiles()
  71  * - setShowPreview()
  72  * - indicateActivationChange()
  73  * - setZoomLevel()
  74  */
  75 class LIBDOLPHINPRIVATE_EXPORT DolphinController : public QObject
  76 {
  77     Q_OBJECT
  78
  79 public:
  80     explicit DolphinController(DolphinView* dolphinView);
  81     virtual ~DolphinController();
  82
  83     /**
  84      * Allows read access for the the view implementation to the abstract
  85      * Dolphin view.
  86      */
  87     const DolphinView* dolphinView() const;
  88
  89     /**
  90      * Sets the URL to \a url and emits the signal urlChanged() if
  91      * \a url is different for the current URL. This method should
  92      * be invoked by the abstract Dolphin view whenever the current
  93      * URL has been changed.
  94      */
  95     void setUrl(const KUrl& url);
  96     const KUrl& url() const;
  97
  98     /**
  99      * Changes the current item view where the controller is working. This
 100      * is only necessary for views like the tree view, where internally
 101      * several QAbstractItemView instances are used.
 102      */
 103     void setItemView(QAbstractItemView* view);
 104
 105     QAbstractItemView* itemView() const;
 106
 107     /**
 108      * Allows a view implementation to request an URL change to \a url.
 109      * The signal requestUrlChange() is emitted and the abstract Dolphin view
 110      * will assure that the URL of the Dolphin Controller will be updated
 111      * later. Invoking this method makes only sense if the view implementation
 112      * shows a hierarchy of URLs and allows to change the URL within
 113      * the view (e. g. this is the case in the column view).
 114      */
 115     void triggerUrlChangeRequest(const KUrl& url);
 116
 117     /**
 118      * Requests a context menu for the position \a pos. This method
 119      * should be invoked by the view implementation when a context
 120      * menu should be opened. The abstract Dolphin view itself
 121      * takes care itself to get the selected items depending from
 122      * \a pos.
 123      */
 124     void triggerContextMenuRequest(const QPoint& pos);
 125
 126     /**
 127      * Requests an activation of the view and emits the signal
 128      * activated(). This method should be invoked by the view implementation
 129      * if e. g. a mouse click on the view has been done.
 130      * After the activation has been changed, the view implementation
 131      * might listen to the activationChanged() signal.
 132      */
 133     void requestActivation();
 134
 135     /**
 136      * Indicates that URLs are dropped above a destination. This method
 137      * should be invoked by the view implementation. The abstract Dolphin view
 138      * will start the corresponding action (copy, move, link).
 139      * @param urls      URLs that are dropped above a destination.
 140      * @param destPath  Path of the destination.
 141      * @param destItem  Destination item (can be null, see KFileItem::isNull()).
 142      */
 143     void indicateDroppedUrls(const KUrl::List& urls,
 144                              const KUrl& destPath,
 145                              const KFileItem& destItem);
 146
 147     /**
 148      * Informs the abstract Dolphin view about a sorting change done inside
 149      * the view implementation. This method should be invoked by the view
 150      * implementation (e. g. the details view uses this method in combination
 151      * with the details header).
 152      */
 153     void indicateSortingChange(DolphinView::Sorting sorting);
 154
 155     /**
 156      * Informs the abstract Dolphin view about a sort order change done inside
 157      * the view implementation. This method should be invoked by the view
 158      * implementation (e. g. the details view uses this method in combination
 159      * with the details header).
 160      */
 161     void indicateSortOrderChange(Qt::SortOrder order);
 162
 163     /**
 164      * Informs the abstract Dolphin view about an additional information change
 165      * done inside the view implementation. This method should be invoked by the
 166      * view implementation (e. g. the details view uses this method in combination
 167      * with the details header).
 168      */
 169     void indicateAdditionalInfoChange(const KFileItemDelegate::InformationList& info);
 170
 171     /**
 172      * Informs the view implementation about a change of the activation
 173      * state and is invoked by the abstract Dolphin view. The signal
 174      * activationChanged() is emitted.
 175      */
 176     void indicateActivationChange(bool active);
 177
 178     /**
 179      * Sets the zoom level to \a level and emits the signal zoomLevelChanged().
 180      * It must be assured that the used level is inside the range
 181      * DolphinController::zoomLevelMinimum() and
 182      * DolphinController::zoomLevelMaximum().
 183      * Is invoked by the abstract Dolphin view.
 184      */
 185     void setZoomLevel(int level);
 186     int zoomLevel() const;
 187
 188     int zoomLevelMinimum() const;
 189     int zoomLevelMaximum() const;
 190
 191     /**
 192      * Helper method for the view implementation to get
 193      * the icon size for the zoom level \a level
 194      * (see DolphinController::zoomLevel()).
 195      */
 196     static int iconSizeForZoomLevel(int level);
 197
 198     /**
 199      * Tells the view implementation to zoom out by emitting the signal zoomOut()
 200      * and is invoked by the abstract Dolphin view.
 201      */
 202     void triggerZoomOut();
 203
 204     /**
 205      * Should be invoked in each view implementation whenever a key has been
 206      * pressed. If the selection model of \a view is not empty and
 207      * the return key has been pressed, the selected items will get triggered.
 208      */
 209     void handleKeyPressEvent(QKeyEvent* event);
 210
 211     /**
 212      * Replaces the URL of the abstract Dolphin view  with the content
 213      * of the clipboard as URL. If the clipboard contains no text,
 214      * nothing will be done.
 215      */
 216     void replaceUrlByClipboard();
 217
 218     /**
 219      * Returns the file item for the proxy index \a index of the view \a view.
 220      */
 221     KFileItem itemForIndex(const QModelIndex& index) const;
 222
 223 public slots:
 224     /**
 225      * Emits the signal itemTriggered() if the file item for the index \a index
 226      * is not null. The method should be invoked by the
 227      * controller parent whenever the user has triggered an item.
 228      */
 229     void triggerItem(const QModelIndex& index);
 230
 231     /**
 232      * Emits the signal itemEntered() if the file item for the index \a index
 233      * is not null. The method should be invoked by the controller parent
 234      * whenever the mouse cursor is above an item.
 235      */
 236     void emitItemEntered(const QModelIndex& index);
 237
 238     /**
 239      * Emits the signal viewportEntered(). The method should be invoked by
 240      * the controller parent whenever the mouse cursor is above the viewport.
 241      */
 242     void emitViewportEntered();
 243
 244 signals:
 245     /**
 246      * Is emitted if the URL for the Dolphin controller has been changed
 247      * to \a url.
 248      */
 249     void urlChanged(const KUrl& url);
 250
 251     /**
 252      * Is emitted if the view implementation requests a changing of the current
 253      * URL to \a url (see triggerUrlChangeRequest()).
 254      */
 255     void requestUrlChange(const KUrl& url);
 256
 257     /**
 258      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 259      * The abstract Dolphin view connects to this signal and will open the context menu.
 260      * @param pos       Position relative to the view widget where the
 261      *                  context menu should be opened. It is recommended
 262      *                  to get the corresponding model index from
 263      *                  this position.
 264      */
 265     void requestContextMenu(const QPoint& pos);
 266
 267     /**
 268      * Is emitted if the view has been activated by e. g. a mouse click.
 269      * The abstract Dolphin view connects to this signal to know the
 270      * destination view for the menu actions.
 271      */
 272     void activated();
 273
 274     /**
 275      * Is emitted if the URLs \a urls have been dropped to the destination
 276      * path \a destPath. If the URLs have been dropped above an item of
 277      * the destination path, the item is indicated by \a destItem
 278      * (can be null, see KFileItem::isNull()).
 279      */
 280     void urlsDropped(const KUrl::List& urls,
 281                      const KUrl& destPath,
 282                      const KFileItem& destItem);
 283
 284     /**
 285      * Is emitted if the sorting has been changed to \a sorting by
 286      * the view implementation (see indicateSortingChanged().
 287      * The abstract Dolphin view connects to
 288      * this signal to update its menu action.
 289      */
 290     void sortingChanged(DolphinView::Sorting sorting);
 291
 292     /**
 293      * Is emitted if the sort order has been changed to \a order
 294      * by the view implementation (see indicateSortOrderChanged().
 295      * The abstract Dolphin view connects
 296      * to this signal to update its menu actions.
 297      */
 298     void sortOrderChanged(Qt::SortOrder order);
 299
 300     /**
 301      * Is emitted if the additional info has been changed to \a info
 302      * by the view implementation. The abstract Dolphin view connects
 303      * to this signal to update its menu actions.
 304      */
 305     void additionalInfoChanged(const KFileItemDelegate::InformationList& info);
 306
 307     /**
 308      * Is emitted if the activation state has been changed to \a active
 309      * by the abstract Dolphin view.
 310      * The view implementation might connect to this signal if custom
 311      * updates are required in this case.
 312      */
 313     void activationChanged(bool active);
 314
 315     /**
 316      * Is emitted if the item \a item should be triggered. The abstract
 317      * Dolphin view connects to this signal. If the item represents a directory,
 318      * the directory is opened. On a file the corresponding application is opened.
 319      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 320      */
 321     void itemTriggered(const KFileItem& item);
 322
 323     /**
 324      * Is emitted if the mouse cursor has entered the item
 325      * given by \a index (see emitItemEntered()).
 326      * The abstract Dolphin view connects to this signal.
 327      */
 328     void itemEntered(const KFileItem& item);
 329
 330     /**
 331      * Is emitted if a new tab should be opened for the URL \a url.
 332      */
 333     void tabRequested(const KUrl& url);
 334
 335     /**
 336      * Is emitted if the mouse cursor has entered
 337      * the viewport (see emitViewportEntered().
 338      * The abstract Dolphin view connects to this signal.
 339      */
 340     void viewportEntered();
 341
 342     /**
 343      * Is emitted if the view should change the zoom to \a level. The view implementation
 344      * must connect to this signal if it supports zooming.
 345      */
 346     void zoomLevelChanged(int level);
 347
 348 private slots:
 349     void updateOpenTabState();
 350
 351 private:
 352     int m_zoomLevel;
 353     bool m_openTab; // TODO: this is a workaround until  Qt-issue 176832 has been fixed
 354     KUrl m_url;
 355     DolphinView* m_dolphinView;
 356     QAbstractItemView* m_itemView;
 357 };
 358
 359 inline const DolphinView* DolphinController::dolphinView() const
 360 {
 361     return m_dolphinView;
 362 }
 363
 364 inline const KUrl& DolphinController::url() const
 365 {
 366     return m_url;
 367 }
 368
 369 inline QAbstractItemView* DolphinController::itemView() const
 370 {
 371     return m_itemView;
 372 }
 373
 374 inline int DolphinController::zoomLevel() const
 375 {
 376     return m_zoomLevel;
 377 }
 378
 379 inline int DolphinController::zoomLevelMinimum() const
 380 {
 381     return 0;
 382 }
 383
 384 inline int DolphinController::zoomLevelMaximum() const
 385 {
 386     return 6;
 387 }
 388
 389 #endif