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 KUrl;
  29 class QBrush;
  30 class QModelIndex;
  31 class QPoint;
  32 class QRect;
  33 class QWidget;
  34
  35 /**
  36  * @brief Acts as mediator between the abstract Dolphin view and the view
  37  *        implementations.
  38  *
  39  * The abstract Dolphin view (see DolphinView) represents the parent of the controller.
  40  * The controller is passed to the current view implementation
  41  * (see DolphinIconsView, DolphinDetailsView and DolphinColumnView)
  42  * by passing it in the constructor:
  43  *
  44  * \code
  45  * DolphinController* controller = new DolphinController(parent);
  46  * QAbstractItemView* view = new DolphinIconsView(parent, controller);
  47  * \endcode
  48  *
  49  * The communication of the view implementations to the abstract view is done by:
  50  * - triggerContextMenuRequest()
  51  * - requestActivation()
  52  * - triggerUrlChangeRequest()
  53  * - indicateDroppedUrls()
  54  * - indicateSortingChange()
  55  * - indicateSortOrderChanged()
  56  * - setZoomInPossible()
  57  * - setZoomOutPossible()
  58  * - triggerItem()
  59  * - emitItemEntered()
  60  * - emitViewportEntered()
  61  *
  62  * The communication of the abstract view to the view implementations is done by:
  63  * - setUrl()
  64  * - setShowHiddenFiles()
  65  * - setShowPreview()
  66  * - setAdditionalInfoCount()
  67  * - indicateActivationChange()
  68  * - triggerZoomIn()
  69  * - triggerZoomOut()
  70  */
  71 class LIBDOLPHINPRIVATE_EXPORT DolphinController : public QObject
  72 {
  73     Q_OBJECT
  74
  75 public:
  76     explicit DolphinController(QObject* parent);
  77     virtual ~DolphinController();
  78
  79     /**
  80      * Sets the URL to \a url and emits the signal urlChanged() if
  81      * \a url is different for the current URL. This method should
  82      * be invoked by the abstract Dolphin view whenever the current
  83      * URL has been changed.
  84      */
  85     void setUrl(const KUrl& url);
  86     const KUrl& url() const;
  87
  88     /**
  89      * Allows a view implementation to request an URL change to \a url.
  90      * The signal requestUrlChange() is emitted and the abstract Dolphin view
  91      * will assure that the URL of the Dolphin Controller will be updated
  92      * later. Invoking this method makes only sense if the view implementation
  93      * shows a hierarchy of URLs and allows to change the URL within
  94      * the view (e. g. this is the case in the column view).
  95      */
  96     void triggerUrlChangeRequest(const KUrl& url);
  97
  98     /**
  99      * Requests a context menu for the position \a pos. This method
 100      * should be invoked by the view implementation when a context
 101      * menu should be opened. The abstract Dolphin view itself
 102      * takes care itself to get the selected items depending from
 103      * \a pos.
 104      */
 105     void triggerContextMenuRequest(const QPoint& pos);
 106
 107     /**
 108      * Requests an activation of the view and emits the signal
 109      * activated(). This method should be invoked by the view implementation
 110      * if e. g. a mouse click on the view has been done.
 111      * After the activation has been changed, the view implementation
 112      * might listen to the activationChanged() signal.
 113      */
 114     void requestActivation();
 115
 116     /**
 117      * Indicates that URLs are dropped above a destination. This method
 118      * should be invoked by the view implementation. The abstract Dolphin view
 119      * will start the corresponding action (copy, move, link).
 120      * @param urls      URLs that are dropped above a destination.
 121      * @param destPath  Path of the destination.
 122      * @param destIndex Model index of the destination item.
 123      * @param source    Pointer to the view implementation which invoked this method.
 124      */
 125     void indicateDroppedUrls(const KUrl::List& urls,
 126                              const KUrl& destPath,
 127                              const QModelIndex& destIndex,
 128                              QWidget* source);
 129
 130     /**
 131      * Informs the abstract Dolphin view about a sorting change done inside
 132      * the view implementation. This method should be invoked by the view
 133      * implementation (e. g. the details view uses this method in combination
 134      * with the details header).
 135      */
 136     void indicateSortingChange(DolphinView::Sorting sorting);
 137
 138     /**
 139      * Informs the abstract Dolphin view about a sort order change done inside
 140      * the view implementation. This method should be invoked by the view
 141      * implementation (e. g. the details view uses this method in combination
 142      * with the details header).
 143      */
 144     void indicateSortOrderChange(Qt::SortOrder order);
 145
 146     /**
 147      * Informs the view implementation about a change of the show hidden files
 148      * state and is invoked by the abstract Dolphin view.
 149      * The signal showHiddenFilesChanged() is emitted.
 150      */
 151     void setShowHiddenFiles(bool show);
 152     bool showHiddenFiles() const;
 153
 154     /**
 155      * Informs the view implementation about a change of the show preview
 156      * state and is invoked by the abstract Dolphin view.
 157      * The signal showPreviewChanged() is emitted.
 158      */
 159     void setShowPreview(bool show);
 160     bool showPreview() const;
 161
 162     /**
 163      * Informs the view implementation about a change of the number of
 164      * additional informations and is invoked by the abstract Dolphin view.
 165      * The signal additionalInfoCountChanged() is emitted.
 166      */
 167     void setAdditionalInfoCount(int count);
 168     bool additionalInfoCount() const;
 169
 170     /**
 171      * Informs the view implementation about a change of the activation
 172      * state and is invoked by the abstract Dolphin view. The signal
 173      * activationChanged() is emitted.
 174      */
 175     void indicateActivationChange(bool active);
 176
 177     /**
 178      * Tells the view implementation to zoom in by emitting the signal zoomIn()
 179      * and is invoked by the abstract Dolphin view.
 180      */
 181     void triggerZoomIn();
 182
 183     /**
 184      * Is invoked by the view implementation to indicate whether a zooming in
 185      * is possible. The abstract Dolphin view updates the corresponding menu
 186      * action depending on this state.
 187      */
 188     void setZoomInPossible(bool possible);
 189     bool isZoomInPossible() const;
 190
 191     /**
 192      * Tells the view implementation to zoom out by emitting the signal zoomOut()
 193      * and is invoked by the abstract Dolphin view.
 194      */
 195     void triggerZoomOut();
 196
 197     /**
 198      * Is invoked by the view implementation to indicate whether a zooming out
 199      * is possible. The abstract Dolphin view updates the corresponding menu
 200      * action depending on this state.
 201      */
 202     void setZoomOutPossible(bool possible);
 203     bool isZoomOutPossible() const;
 204
 205     // TODO: remove this method when the issue #160611 is solved in Qt 4.4
 206     static void drawHoverIndication(QWidget* widget,
 207                                     const QRect& bounds,
 208                                     const QBrush& brush);
 209
 210 public slots:
 211     /**
 212      * Emits the signal itemTriggered(). The method should be invoked by the
 213      * controller parent whenever the user has triggered an item. */
 214     void triggerItem(const KFileItem& item);
 215
 216     /**
 217      * Emits the signal itemEntered(). The method should be invoked by
 218      * the controller parent whenever the mouse cursor is above an item.
 219      */
 220     void emitItemEntered(const KFileItem& item);
 221
 222     /**
 223      * Emits the signal viewportEntered(). The method should be invoked by
 224      * the controller parent whenever the mouse cursor is above the viewport.
 225      */
 226     void emitViewportEntered();
 227
 228 signals:
 229     /**
 230      * Is emitted if the URL for the Dolphin controller has been changed
 231      * to \a url.
 232      */
 233     void urlChanged(const KUrl& url);
 234
 235     /**
 236      * Is emitted if the view implementation requests a changing of the current
 237      * URL to \a url (see triggerUrlChangeRequest()).
 238      */
 239     void requestUrlChange(const KUrl& url);
 240
 241     /**
 242      * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
 243      * The abstract Dolphin view connects to this signal and will open the context menu.
 244      * @param pos       Position relative to the view widget where the
 245      *                  context menu should be opened. It is recommended
 246      *                  to get the corresponding model index from
 247      *                  this position.
 248      */
 249     void requestContextMenu(const QPoint& pos);
 250
 251     /**
 252      * Is emitted if the view has been activated by e. g. a mouse click.
 253      * The abstract Dolphin view connects to this signal to know the
 254      * destination view for the menu actions.
 255      */
 256     void activated();
 257
 258     /**
 259      * Is emitted if the URLs \a urls have been dropped to the destination
 260      * path \a destPath. If the URLs have been dropped above an item of
 261      * the destination path, the item is indicated by \a destIndex.
 262      * \a source indicates the widget where the dragging has been started from.
 263      */
 264     void urlsDropped(const KUrl::List& urls,
 265                      const KUrl& destPath,
 266                      const QModelIndex& destIndex,
 267                      QWidget* source);
 268
 269     /**
 270      * Is emitted if the sorting has been changed to \a sorting by
 271      * the view implementation (see indicateSortingChanged().
 272      * The abstract Dolphin view connects to
 273      * this signal to update its menu action.
 274      */
 275     void sortingChanged(DolphinView::Sorting sorting);
 276
 277     /**
 278      * Is emitted if the sort order has been changed to \a order
 279      * by the view implementation (see indicateSortOrderChanged().
 280      * The abstract Dolphin view connects
 281      * to this signal to update its menu actions.
 282      */
 283     void sortOrderChanged(Qt::SortOrder order);
 284
 285     /**
 286      * Is emitted if the state for showing hidden files has been
 287      * changed to \a show by the abstract Dolphin view. The view
 288      * implementation might connect to this signal if custom
 289      * updates are required in this case.
 290      */
 291     void showHiddenFilesChanged(bool show);
 292
 293     /**
 294      * Is emitted if the state for showing previews has been
 295      * changed to \a show by the abstract Dolphin view.
 296      * The view implementation might connect to this signal if custom
 297      * updates are required in this case.
 298      */
 299     void showPreviewChanged(bool show);
 300
 301     /**
 302      * Is emitted if the number of additional informations has been
 303      * changed to \a count by the abstract Dolphin view.
 304      * The view implementation might connect to this signal if custom
 305      * updates are required in this case.
 306      */
 307     void additionalInfoCountChanged(int count);
 308
 309     /**
 310      * Is emitted if the activation state has been changed to \a active
 311      * by the abstract Dolphin view.
 312      * The view implementation might connect to this signal if custom
 313      * updates are required in this case.
 314      */
 315     void activationChanged(bool active);
 316
 317     /**
 318      * Is emitted if the item \a item should be triggered. The abstract
 319      * Dolphin view connects to this signal. If the item represents a directory,
 320      * the directory is opened. On a file the corresponding application is opened.
 321      * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
 322      */
 323     void itemTriggered(const KFileItem& item);
 324
 325     /**
 326      * Is emitted if the mouse cursor has entered the item
 327      * given by \a index (see emitItemEntered()).
 328      * The abstract Dolphin view connects to this signal.
 329      */
 330     void itemEntered(const KFileItem& item);
 331
 332     /**
 333      * Is emitted if the mouse cursor has entered
 334      * the viewport (see emitViewportEntered().
 335      * The abstract Dolphin view connects to this signal.
 336      */
 337     void viewportEntered();
 338
 339     /**
 340      * Is emitted if the view should zoom in. The view implementation
 341      * must connect to this signal if it supports zooming.
 342      */
 343     void zoomIn();
 344
 345     /**
 346      * Is emitted if the view should zoom out. The view implementation
 347      * must connect to this signal if it supports zooming.
 348      */
 349     void zoomOut();
 350
 351 private:
 352     bool m_showHiddenFiles;
 353     bool m_showPreview;
 354     bool m_zoomInPossible;
 355     bool m_zoomOutPossible;
 356     int m_additionalInfoCount;
 357     KUrl m_url;
 358 };
 359
 360 inline const KUrl& DolphinController::url() const
 361 {
 362     return m_url;
 363 }
 364
 365 inline bool DolphinController::showHiddenFiles() const
 366 {
 367     return m_showHiddenFiles;
 368 }
 369
 370 inline bool DolphinController::showPreview() const
 371 {
 372     return m_showPreview;
 373 }
 374
 375 inline bool DolphinController::additionalInfoCount() const
 376 {
 377     return m_additionalInfoCount;
 378 }
 379
 380 inline void DolphinController::setZoomInPossible(bool possible)
 381 {
 382     m_zoomInPossible = possible;
 383 }
 384
 385 inline bool DolphinController::isZoomInPossible() const
 386 {
 387     return m_zoomInPossible;
 388 }
 389
 390 inline void DolphinController::setZoomOutPossible(bool possible)
 391 {
 392     m_zoomOutPossible = possible;
 393 }
 394
 395 inline bool DolphinController::isZoomOutPossible() const
 396 {
 397     return m_zoomOutPossible;
 398 }
 399
 400 #endif