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