* assure that the columns of the colum-view get dimmed if the colum-view is inactive

* updated documentation of DolphinController + minor cleanups

svn path=/trunk/KDE/kdebase/apps/; revision=722452

10 files changed, 240 insertions, 74 deletions

diff --git a/src/dolphincolumnview.cpp b/src/dolphincolumnview.cpp
index 79270d184..fac35a0be 100644
--- a/src/dolphincolumnview.cpp
+++ b/src/dolphincolumnview.cpp
@@ -43,7 +43,7 @@
 DolphinColumnView::DolphinColumnView(QWidget* parent, DolphinController* controller) :
     QAbstractItemView(parent),
     m_controller(controller),
-    m_restoreActiveColumnFocus(false),
+    m_active(false),
     m_index(-1),
     m_contentX(0),
     m_columns(),
@@ -68,6 +68,8 @@ DolphinColumnView::DolphinColumnView(QWidget* parent, DolphinController* control
             this, SLOT(slotShowHiddenFilesChanged(bool)));
     connect(controller, SIGNAL(showPreviewChanged(bool)),
             this, SLOT(slotShowPreviewChanged(bool)));
+    connect(controller, SIGNAL(activationChanged(bool)),
+            this, SLOT(updateColumnsBackground(bool)));
 
     connect(horizontalScrollBar(), SIGNAL(valueChanged(int)),
             this, SLOT(moveContentHorizontally(int)));
@@ -80,15 +82,7 @@ DolphinColumnView::DolphinColumnView(QWidget* parent, DolphinController* control
     setActiveColumnIndex(0);
 
     updateDecorationSize();
-
-    // dim the background of the viewport
-    QColor bgColor = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
-    const QColor fgColor = KColorScheme(QPalette::Active, KColorScheme::View).foreground().color();
-    bgColor = KColorUtils::mix(bgColor, fgColor, 0.04);
-
-    QPalette palette = viewport()->palette();
-    palette.setColor(viewport()->backgroundRole(), bgColor);
-    viewport()->setPalette(palette);
+    updateColumnsBackground(true);
 }
 
 DolphinColumnView::~DolphinColumnView()
@@ -310,7 +304,7 @@ int DolphinColumnView::verticalOffset() const
 
 void DolphinColumnView::mousePressEvent(QMouseEvent* event)
 {
-    m_controller->triggerActivation();
+    m_controller->requestActivation();
     QAbstractItemView::mousePressEvent(event);
 }
 
@@ -371,6 +365,27 @@ void DolphinColumnView::updateDecorationSize()
     doItemsLayout();
 }
 
+void DolphinColumnView::updateColumnsBackground(bool active)
+{
+    if (active == m_active) {
+        return;
+    }
+
+    m_active = active;
+
+    // dim the background of the viewport
+    QColor color = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
+    color.setAlpha(150);
+
+    QPalette palette;
+    palette.setColor(viewport()->backgroundRole(), color);
+    viewport()->setPalette(palette);
+
+    foreach (DolphinColumnWidget* column, m_columns) {
+        column->updateBackground();
+    }
+}
+
 void DolphinColumnView::slotShowHiddenFilesChanged(bool show)
 {
     foreach (DolphinColumnWidget* column, m_columns) {
diff --git a/src/dolphincolumnview.h b/src/dolphincolumnview.h
index 6837815a0..80228a84c 100644
--- a/src/dolphincolumnview.h
+++ b/src/dolphincolumnview.h
@@ -108,6 +108,12 @@ private slots:
      */
     void updateDecorationSize();
 
+    /**
+     * Updates the background color of the columns to respect
+     * the current activation state \a active.
+     */
+    void updateColumnsBackground(bool active);
+
     void slotShowHiddenFilesChanged(bool show);
     void slotShowPreviewChanged(bool show);
 
@@ -146,7 +152,7 @@ private:
 
 private:
     DolphinController* m_controller;
-    bool m_restoreActiveColumnFocus;
+    bool m_active;
     int m_index;
     int m_contentX;
     QList<DolphinColumnWidget*> m_columns;
diff --git a/src/dolphincolumnwidget.cpp b/src/dolphincolumnwidget.cpp
index eea70a8e3..3b38b6cd5 100644
--- a/src/dolphincolumnwidget.cpp
+++ b/src/dolphincolumnwidget.cpp
@@ -177,6 +177,19 @@ void DolphinColumnWidget::setShowPreview(bool show)
     }
 }
 
+void DolphinColumnWidget::updateBackground()
+{
+    QColor color = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
+    if (!m_active || !m_view->m_active) {
+        color.setAlpha(0);
+    }
+    QPalette palette = viewport()->palette();
+    palette.setColor(viewport()->backgroundRole(), color);
+    viewport()->setPalette(palette);
+
+    update();
+}
+
 void DolphinColumnWidget::dragEnterEvent(QDragEnterEvent* event)
 {
     if (event->mimeData()->hasUrls()) {
@@ -252,7 +265,7 @@ void DolphinColumnWidget::paintEvent(QPaintEvent* event)
 
 void DolphinColumnWidget::mousePressEvent(QMouseEvent* event)
 {
-    m_view->m_controller->triggerActivation();
+    m_view->m_controller->requestActivation();
     if (!m_active) {
         m_view->requestActivation(this);
     }
@@ -367,11 +380,6 @@ void DolphinColumnWidget::activate()
                 this, SLOT(triggerItem(const QModelIndex&)));
     }
 
-    const QColor bgColor = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
-    QPalette palette = viewport()->palette();
-    palette.setColor(viewport()->backgroundRole(), bgColor);
-    viewport()->setPalette(palette);
-
     if (!m_childUrl.isEmpty()) {
         // assure that the current index is set on the index that represents
         // the child URL
@@ -380,7 +388,7 @@ void DolphinColumnWidget::activate()
         selectionModel()->setCurrentIndex(proxyIndex, QItemSelectionModel::Current);
     }
 
-    update();
+    updateBackground();
 }
 
 void DolphinColumnWidget::deactivate()
@@ -396,11 +404,8 @@ void DolphinColumnWidget::deactivate()
                    this, SLOT(triggerItem(const QModelIndex&)));
     }
 
-    const QPalette palette = m_view->viewport()->palette();
-    viewport()->setPalette(palette);
-
     selectionModel()->clear();
-    update();
+    updateBackground();
 }
 
 bool DolphinColumnWidget::isCutItem(const KFileItem& item) const
diff --git a/src/dolphincolumnwidget.h b/src/dolphincolumnwidget.h
index 0efce0902..03e082658 100644
--- a/src/dolphincolumnwidget.h
+++ b/src/dolphincolumnwidget.h
@@ -78,6 +78,12 @@ public:
     void setShowHiddenFiles(bool show);
     void setShowPreview(bool show);
 
+    /**
+     * Updates the background color dependent from the activation state
+     * \a isViewActive of the column view.
+     */
+    void updateBackground();
+
 protected:
     virtual QStyleOptionViewItem viewOptions() const;
     virtual void dragEnterEvent(QDragEnterEvent* event);
diff --git a/src/dolphincontroller.cpp b/src/dolphincontroller.cpp
index 59cc20f0f..7a6d56637 100644
--- a/src/dolphincontroller.cpp
+++ b/src/dolphincontroller.cpp
@@ -50,7 +50,7 @@ void DolphinController::triggerContextMenuRequest(const QPoint& pos)
     emit requestContextMenu(pos);
 }
 
-void DolphinController::triggerActivation()
+void DolphinController::requestActivation()
 {
     emit activated();
 }
@@ -98,6 +98,11 @@ void DolphinController::setAdditionalInfoCount(int count)
     }
 }
 
+void DolphinController::indicateActivationChange(bool active)
+{
+    emit activationChanged(active);
+}
+
 void DolphinController::triggerZoomIn()
 {
     emit zoomIn();
diff --git a/src/dolphincontroller.h b/src/dolphincontroller.h
index 31b80e7bf..118b945f0 100644
--- a/src/dolphincontroller.h
+++ b/src/dolphincontroller.h
@@ -33,21 +33,38 @@ class QRect;
 class QWidget;
 
 /**
- * @brief Allows to control Dolphin views and to react on state changes.
+ * @brief Acts as mediator between the abstract Dolphin view and the view
+ *        implementations.
  *
- * One instance of a DolphinController can be assigned to a variable number of
- * Dolphin views (DolphinIconsView, DolphinDetailsView) by passing it in
- * the constructor:
+ * The abstract Dolphin view (see DolphinView) represents the parent of the controller.
+ * The controller is passed to the current view implementation
+ * (see DolphinIconsView, DolphinDetailsView and DolphinColumnView)
+ * by passing it in the constructor:
  *
  * \code
  * DolphinController* controller = new DolphinController(parent);
- * DolphinDetailsView* detailsView = new DolphinDetailsView(parent, controller);
- * DolphinIconsView* iconsView = new DolphinIconsView(parent, controller);
+ * QAbstractItemView* view = new DolphinIconsView(parent, controller);
  * \endcode
  *
- * The Dolphin view assures that the controller gets informed about selection changes,
- * when an item should be triggered and a lot more. The controller emits the corresponding signals
- * so that the receiver may react on those changes.
+ * The communication of the view implementations to the abstract view is done by:
+ * - triggerContextMenuRequest()
+ * - requestActivation()
+ * - indicateDroppedUrls()
+ * - indicateSortingChange()
+ * - indicateSortOrderChanged()
+ * - setZoomInPossible()
+ * - setZoomOutPossible()
+ * - triggerItem()
+ * - emitItemEntered()
+ * - emitViewportEntered()
+ *
+ * The communication of the abstract view to the view implementations is done by:
+ * - setShowHiddenFiles()
+ * - setShowPreview()
+ * - setAdditionalInfoCount()
+ * - indicateActivationChange()
+ * - triggerZoomIn()
+ * - triggerZoomOut()
  */
 class LIBDOLPHINPRIVATE_EXPORT DolphinController : public QObject
 {
@@ -61,33 +78,110 @@ public:
     void setUrl(const KUrl& url);
     const KUrl& url() const;
 
+    /**
+     * Requests a context menu for the position \a pos. This method
+     * should be invoked by the view implementation when a context
+     * menu should be opened. The abstract Dolphin view itself
+     * takes care itself to get the selected items depending from
+     * \a pos.
+     */
     void triggerContextMenuRequest(const QPoint& pos);
 
-    void triggerActivation();
+    /**
+     * Requests an activation of the view and emits the signal
+     * activated(). This method should be invoked by the view implementation
+     * if e. g. a mouse click on the view has been done.
+     * After the activation has been changed, the view implementation
+     * might listen to the activationChanged() signal.
+     */
+    void requestActivation();
 
+    /**
+     * Indicates that URLs are dropped above a destination. This method
+     * should be invoked by the view implementation. The abstract Dolphin view
+     * will start the corresponding action (copy, move, link).
+     * @param urls      URLs that are dropped above a destination.
+     * @param destPath  Path of the destination.
+     * @param destIndex Model index of the destination item.
+     * @param source    Pointer to the view implementation which invoked this method.
+     */
     void indicateDroppedUrls(const KUrl::List& urls,
                              const KUrl& destPath,
                              const QModelIndex& destIndex,
                              QWidget* source);
 
+    /**
+     * Informs the abstract Dolphin view about a sorting change done inside
+     * the view implementation. This method should be invoked by the view
+     * implementation (e. g. the details view uses this method in combination
+     * with the details header).
+     */
     void indicateSortingChange(DolphinView::Sorting sorting);
 
+    /**
+     * Informs the abstract Dolphin view about a sort order change done inside
+     * the view implementation. This method should be invoked by the view
+     * implementation (e. g. the details view uses this method in combination
+     * with the details header).
+     */
     void indicateSortOrderChange(Qt::SortOrder order);
 
+    /**
+     * Informs the view implementation about a change of the show hidden files
+     * state and is invoked by the abstract Dolphin view.
+     * The signal showHiddenFilesChanged() is emitted.
+     */
     void setShowHiddenFiles(bool show);
     bool showHiddenFiles() const;
 
+    /**
+     * Informs the view implementation about a change of the show preview
+     * state and is invoked by the abstract Dolphin view.
+     * The signal showPreviewChanged() is emitted.
+     */
     void setShowPreview(bool show);
     bool showPreview() const;
 
+    /**
+     * Informs the view implementation about a change of the number of
+     * additional informations and is invoked by the abstract Dolphin view.
+     * The signal additionalInfoCountChanged() is emitted.
+     */
     void setAdditionalInfoCount(int count);
     bool additionalInfoCount() const;
 
+    /**
+     * Informs the view implementation about a change of the activation
+     * state and is invoked by the abstract Dolphin view. The signal
+     * activationChanged() is emitted.
+     */
+    void indicateActivationChange(bool active);
+
+    /**
+     * Tells the view implementation to zoom in by emitting the signal zoomIn()
+     * and is invoked by the abstract Dolphin view.
+     */
     void triggerZoomIn();
+
+    /**
+     * Is invoked by the view implementation to indicate whether a zooming in
+     * is possible. The abstract Dolphin view updates the corresponding menu
+     * action depending on this state.
+     */
     void setZoomInPossible(bool possible);
     bool isZoomInPossible() const;
 
+    /**
+     * Tells the view implementation to zoom out by emitting the signal zoomOut()
+     * and is invoked by the abstract Dolphin view.
+     */
     void triggerZoomOut();
+
+    /**
+     * Is invoked by the view implementation to indicate whether a zooming out
+     * is possible. The abstract Dolphin view updates the corresponding menu
+     * action depending on this state.
+     */
     void setZoomOutPossible(bool possible);
     bool isZoomOutPossible() const;
 
@@ -122,7 +216,8 @@ signals:
     void urlChanged(const KUrl& url);
 
     /**
-     * Is emitted if a context menu should be opened.
+     * Is emitted if a context menu should be opened (see triggerContextMenuRequest()).
+     * The abstract Dolphin view connects to this signal and will open the context menu.
      * @param pos       Position relative to the view widget where the
      *                  context menu should be opened. It is recommended
      *                  to get the corresponding model index from
@@ -132,6 +227,8 @@ signals:
 
     /**
      * Is emitted if the view has been activated by e. g. a mouse click.
+     * The abstract Dolphin view connects to this signal to know the
+     * destination view for the menu actions.
      */
     void activated();
 
@@ -146,53 +243,86 @@ signals:
                      const QModelIndex& destIndex,
                      QWidget* source);
 
-    /** Is emitted if the sorting has been changed to \a sorting. */
+    /**
+     * Is emitted if the sorting has been changed to \a sorting by
+     * the view implementation (see indicateSortingChanged().
+     * The abstract Dolphin view connects to
+     * this signal to update its menu action.
+     */
     void sortingChanged(DolphinView::Sorting sorting);
 
-    /** Is emitted if the sort order has been changed to \a sort order. */
+    /**
+     * Is emitted if the sort order has been changed to \a order
+     * by the view implementation (see indicateSortOrderChanged().
+     * The abstract Dolphin view connects
+     * to this signal to update its menu actions.
+     */
     void sortOrderChanged(Qt::SortOrder order);
 
     /**
      * Is emitted if the state for showing hidden files has been
-     * changed to \a show.
+     * changed to \a show by the abstract Dolphin view. The view
+     * implementation might connect to this signal if custom
+     * updates are required in this case.
      */
     void showHiddenFilesChanged(bool show);
 
     /**
      * Is emitted if the state for showing previews has been
-     * changed to \a show.
+     * changed to \a show by the abstract Dolphin view.
+     * The view implementation might connect to this signal if custom
+     * updates are required in this case.
      */
     void showPreviewChanged(bool show);
 
     /**
      * Is emitted if the number of additional informations has been
-     * changed to \a count.
+     * changed to \a count by the abstract Dolphin view.
+     * The view implementation might connect to this signal if custom
+     * updates are required in this case.
      */
     void additionalInfoCountChanged(int count);
 
     /**
-     * Is emitted if the item \a item should be triggered.
-     * Usually triggering on a directory opens the directory, triggering
-     * on a file opens the corresponding application. The item is null
-     * (see KFileItem::isNull()), when clicking on the viewport itself.
+     * Is emitted if the activation state has been changed to \a active
+     * by the abstract Dolphin view.
+     * The view implementation might connect to this signal if custom
+     * updates are required in this case.
+     */
+    void activationChanged(bool active);
+
+    /**
+     * Is emitted if the item \a item should be triggered. The abstract
+     * Dolphin view connects to this signal. If the item represents a directory,
+     * the directory is opened. On a file the corresponding application is opened.
+     * The item is null (see KFileItem::isNull()), when clicking on the viewport itself.
      */
     void itemTriggered(const KFileItem& item);
 
     /**
      * Is emitted if the mouse cursor has entered the item
-     * given by \a index.
+     * given by \a index (see emitItemEntered()).
+     * The abstract Dolphin view connects to this signal.
      */
     void itemEntered(const KFileItem& item);
 
     /**
      * Is emitted if the mouse cursor has entered
-     * the viewport. */
+     * the viewport (see emitViewportEntered().
+     * The abstract Dolphin view connects to this signal.
+     */
     void viewportEntered();
 
-    /** Is emitted if the view should zoom in. */
+    /**
+     * Is emitted if the view should zoom in. The view implementation
+     * must connect to this signal if it supports zooming.
+     */
     void zoomIn();
 
-    /** Is emitted if the view should zoom out. */
+    /**
+     * Is emitted if the view should zoom out. The view implementation
+     * must connect to this signal if it supports zooming.
+     */
     void zoomOut();
 
 private:
diff --git a/src/dolphindetailsview.cpp b/src/dolphindetailsview.cpp
index 6cd9fbaf9..8e8eec2ec 100644
--- a/src/dolphindetailsview.cpp
+++ b/src/dolphindetailsview.cpp
@@ -193,7 +193,7 @@ void DolphinDetailsView::contextMenuEvent(QContextMenuEvent* event)
 
 void DolphinDetailsView::mousePressEvent(QMouseEvent* event)
 {
-    m_controller->triggerActivation();
+    m_controller->requestActivation();
 
     QTreeView::mousePressEvent(event);
 
diff --git a/src/dolphiniconsview.cpp b/src/dolphiniconsview.cpp
index f1ad25e3d..670dcc13e 100644
--- a/src/dolphiniconsview.cpp
+++ b/src/dolphiniconsview.cpp
@@ -149,7 +149,7 @@ void DolphinIconsView::contextMenuEvent(QContextMenuEvent* event)
 
 void DolphinIconsView::mousePressEvent(QMouseEvent* event)
 {
-    m_controller->triggerActivation();
+    m_controller->requestActivation();
     if (!indexAt(event->pos()).isValid()) {
         const Qt::KeyboardModifiers modifier = QApplication::keyboardModifiers();
         if (!(modifier & Qt::ShiftModifier) && !(modifier & Qt::ControlModifier)) {
diff --git a/src/dolphinview.cpp b/src/dolphinview.cpp
index 75c1ee01c..51dbb708c 100644
--- a/src/dolphinview.cpp
+++ b/src/dolphinview.cpp
@@ -133,12 +133,29 @@ void DolphinView::setActive(bool active)
 
     m_active = active;
 
-    updateViewportColor();
+    QColor color = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
+    if (active) {
+        // TODO: emitting urlChanged() is a hack, as the URL hasn't really changed. It
+        // bypasses the problem when having a split view and changing the active view to
+        // update the some URL dependent states. A nicer approach should be no big deal...
+        emit urlChanged(url());
+        emit selectionChanged(selectedItems());
+    } else {
+        color.setAlpha(150);
+    }
+
+    QWidget* viewport = itemView()->viewport();
+    QPalette palette;
+    palette.setColor(viewport->backgroundRole(), color);
+    viewport->setPalette(palette);
+
     update();
 
     if (active) {
         emit activated();
     }
+
+    m_controller->indicateActivationChange(active);
 }
 
 bool DolphinView::isActive() const
@@ -433,10 +450,14 @@ void DolphinView::reload()
 
 void DolphinView::refresh()
 {
+    const bool oldActivationState = m_active;
+    m_active = true;
+
     createView();
     applyViewProperties(m_controller->url());
     reload();
-    updateViewportColor();
+
+    setActive(oldActivationState);
 }
 
 void DolphinView::updateView(const KUrl& url, const KUrl& rootUrl)
@@ -906,20 +927,4 @@ void DolphinView::applyCutItemEffect()
     }
 }
 
-void DolphinView::updateViewportColor()
-{
-    QColor color = KColorScheme(QPalette::Active, KColorScheme::View).background().color();
-    if (m_active) {
-        emit urlChanged(url()); // Hmm, this is a hack; the url hasn't really changed.
-        emit selectionChanged(selectedItems());
-    } else {
-        color.setAlpha(0);
-    }
-
-    QWidget* viewport = itemView()->viewport();
-    QPalette palette;
-    palette.setColor(viewport->backgroundRole(), color);
-    viewport->setPalette(palette);
-}
-
 #include "dolphinview.moc"
diff --git a/src/dolphinview.h b/src/dolphinview.h
index 6f3b536e2..9291ea8b9 100644
--- a/src/dolphinview.h
+++ b/src/dolphinview.h
@@ -544,12 +544,6 @@ private:
     void applyCutItemEffect();
 
     /**
-     * Updates the color of the viewport depending from the
-     * activation state (see DolphinView::isActive()).
-     */
-    void updateViewportColor();
-
-    /**
      * Returns true, if the ColumnView is activated. As the column view
      * requires some special handling for iterating through directories,
      * this method has been introduced for convenience.