KItemListSmoothScroller: stop animation on property or targetobject change

[dolphin.git] / src / kitemviews / kstandarditemlistwidget.h

diff --git a/src/kitemviews/kstandarditemlistwidget.h b/src/kitemviews/kstandarditemlistwidget.h
index a09f0c7a83090ae384f8d36dcff20c37a0c2fd03..588ec3548e89aea48e70f3aeabda509962a2553b 100644 (file)
--- a/src/kitemviews/kstandarditemlistwidget.h
+++ b/src/kitemviews/kstandarditemlistwidget.h
@@ -11,13 +11,20 @@
 #include "kitemviews/kitemlistwidget.h"
 
 #include <QPixmap>
+#include <QPointer>
 #include <QPointF>
 #include <QStaticText>
 
 class KItemListRoleEditor;
 class KItemListStyleOption;
 class KItemListView;
+class QVariantAnimation;
 
+/**
+ * @brief standard implementation of the ItemList widget informant for use with KStandardItemListView and KStandardItemModel.
+ *
+ * @see KItemListWidgetInformant
+ */
 class DOLPHIN_EXPORT KStandardItemListWidgetInformant : public KItemListWidgetInformant
 {
 public:
@@ -47,12 +54,19 @@ protected:
      */
     virtual bool itemIsLink(int index, const KItemListView *view) const;
 
+    /** Configure whether the requested text should be optimized for viewing on a screen or for being read out aloud by a text-to-speech engine. */
+    enum class ForUsageAs { DisplayedText, SpokenText };
+
     /**
+     * @param role          The role the text is being requested for.
+     * @param values        The data of the item. All the data is passed because the text might depend on multiple data points.
+     * @param forUsageAs    Whether the roleText should be optimized for displaying (i.e. kept somewhat short) or optimized for speaking e.g. by screen readers
+     *                      or text-to-speech in general (i.e. by prefering announcing a month as July instead of as the number 7).
      * @return String representation of the role \a role. The representation of
      *         a role might depend on other roles, so the values of all roles
      *         are passed as parameter.
      */
-    virtual QString roleText(const QByteArray &role, const QHash<QByteArray, QVariant> &values) const;
+    virtual QString roleText(const QByteArray &role, const QHash<QByteArray, QVariant> &values, ForUsageAs forUsageAs = ForUsageAs::DisplayedText) const;
 
     /**
     * @return A font based on baseFont which is customized for symlinks.
@@ -67,7 +81,9 @@ protected:
 };
 
 /**
- * @brief ItemList widget implementation for KStandardItemListView and KStandardItemModel.
+ * @brief standard implementation of an ItemList widget for KStandardItemListView and KStandardItemModel.
+ *
+ * @see KItemListWidget
  */
 class DOLPHIN_EXPORT KStandardItemListWidget : public KItemListWidget
 {
@@ -80,7 +96,6 @@ public:
     ~KStandardItemListWidget() override;
 
     void setLayout(Layout layout);
-    Layout layout() const;
 
     void setHighlightEntireRow(bool highlightEntireRow);
     bool highlightEntireRow() const;
@@ -97,6 +112,8 @@ public:
     QRectF expansionToggleRect() const override;
     QRectF selectionToggleRect() const override;
     QPixmap createDragPixmap(const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override;
+    /** @see KItemListWidget::startActivateSoonAnimation() */
+    void startActivateSoonAnimation(int timeUntilActivation) override;
 
     static KItemListWidgetInformant *createInformant();
 
@@ -149,16 +166,10 @@ protected:
      */
     QString roleText(const QByteArray &role, const QHash<QByteArray, QVariant> &values) const;
 
+    static int numberOfUnicodeCharactersIn(const QString &text);
+
     /**
-     * Fixes:
-     * Select the text without MIME-type extension
-     * This is file-item-specific and should be moved
-     * into KFileItemListWidget.
-     *
-     * Inherited classes can define, if the MIME-type extension
-     * should be selected or not.
-     *
-     * @return Selection length (with or without MIME-type extension)
+     * @return Selection length (with or without MIME-type extension) in number of unicode characters, which might be different from number of QChars.
      */
     virtual int selectionLength(const QString &text) const;
 
@@ -236,6 +247,9 @@ private:
      */
     static qreal columnPadding(const KItemListStyleOption &option);
 
+    /** @returns whether the usual icon should be shown or not. */
+    bool isIconControlledByActivateSoonAnimation() const;
+
 protected:
     QHash<QByteArray, TextInfo *> m_textInfo; // PlacesItemListWidget needs to access this
 
@@ -276,6 +290,9 @@ private:
     KItemListRoleEditor *m_roleEditor;
     KItemListRoleEditor *m_oldRoleEditor;
 
+    /** @see startActivateSoonAnimation() */
+    QPointer<QVariantAnimation> m_activateSoonAnimation;
+
     friend class KStandardItemListWidgetInformant; // Accesses private static methods to be able to
                                                    // share a common layout calculation
 };