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