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