QStyle: deprecate SH_Widget_Animate in favor of SH_Widget_Animation_Duration

This change introduces a new SH_Widget_Animation_Duration style hint
that applications can query instead of manually hardcoding the duration
of an animation.

As default value we use 200, which is the value that was already used in
QWidgetAnimator. A value equal to 0 means that the animations will be
disabled. This also implies that the SH_Widget_Animate style hint is
superseded and can be deprecated.

The new style hint is configurable with style sheets.

[ChangeLog][QtWidgets][Styles] Added SH_Widget_Animation_Duration style
hint which deprecates SH_Widget_Animate.

Change-Id: Ic3f5e4f7145a89697f28666aeaecabb1f3c5c96f
Reviewed-by: Olivier Goffart (Woboq GmbH) <ogoffart@woboq.com>

10 files changed, 41 insertions, 12 deletions

diff --git a/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc b/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc
index dfea9f2ca4..bf727dd380 100644
--- a/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc
+++ b/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc
@@ -1889,3 +1889,7 @@ QTableView::indicator:unchecked {
 }
 //! [161]
 
+//! [162]
+* { widget-animation-duration: 100 }
+//! [162]
+
diff --git a/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc b/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc
index 0131ae18e5..be6a068d65 100644
--- a/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc
+++ b/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc
@@ -2439,6 +2439,22 @@
         \li Whether tool tips are shown on window title bar buttons.
 
     \row
+        \li \b{\c widget-animation-duration*} \target widget-animation-duration
+        \li \l{#Number}{Number}
+        \li How much an animation should last (in milliseconds).
+            A value equal to zero means that the animations will be disabled.
+
+           If this property is not specified, it defaults to the
+           value specified by the current style for the
+           \l{QStyle::}{SH_Widget_Animation_Duration} style hint.
+
+           \b{This property was added in Qt 5.10.}
+
+           Example:
+
+           \snippet code/doc_src_stylesheet.qdoc 162
+
+    \row
         \li \b{\c text-align} \target text-align-prop
         \li \l{#Alignment}{Alignment}
         \li The alignment of text and icon within the contents of the widget.
diff --git a/src/widgets/itemviews/qcolumnview.cpp b/src/widgets/itemviews/qcolumnview.cpp
index ea9bbb0fb9..d94f25de78 100644
--- a/src/widgets/itemviews/qcolumnview.cpp
+++ b/src/widgets/itemviews/qcolumnview.cpp
@@ -53,8 +53,6 @@
 
 QT_BEGIN_NAMESPACE
 
-#define ANIMATION_DURATION_MSEC 150
-
 /*!
     \since 4.3
     \class QColumnView
@@ -107,7 +105,6 @@ void QColumnViewPrivate::initialize()
     q->setTextElideMode(Qt::ElideMiddle);
 #ifndef QT_NO_ANIMATION
     QObject::connect(&currentAnimation, SIGNAL(finished()), q, SLOT(_q_changeCurrentColumn()));
-    currentAnimation.setDuration(ANIMATION_DURATION_MSEC);
     currentAnimation.setTargetObject(hbar);
     currentAnimation.setPropertyName("value");
     currentAnimation.setEasingCurve(QEasingCurve::InOutQuad);
@@ -330,7 +327,8 @@ void QColumnView::scrollTo(const QModelIndex &index, ScrollHint hint)
     }
 
 #ifndef QT_NO_ANIMATION
-    if (style()->styleHint(QStyle::SH_Widget_Animate, 0, this)) {
+    if (const int animationDuration = style()->styleHint(QStyle::SH_Widget_Animation_Duration, 0, this)) {
+        d->currentAnimation.setDuration(animationDuration);
         d->currentAnimation.setEndValue(newScrollbarValue);
         d->currentAnimation.start();
     } else
diff --git a/src/widgets/itemviews/qtreeview.cpp b/src/widgets/itemviews/qtreeview.cpp
index f139fb2d5b..63d6580435 100644
--- a/src/widgets/itemviews/qtreeview.cpp
+++ b/src/widgets/itemviews/qtreeview.cpp
@@ -3051,7 +3051,7 @@ void QTreeViewPrivate::initialize()
     header->setDefaultAlignment(Qt::AlignLeft|Qt::AlignVCenter);
     q->setHeader(header);
 #ifndef QT_NO_ANIMATION
-    animationsEnabled = q->style()->styleHint(QStyle::SH_Widget_Animate, 0, q);
+    animationsEnabled = q->style()->styleHint(QStyle::SH_Widget_Animation_Duration, 0, q) > 0;
     QObject::connect(&animatedOperation, SIGNAL(finished()), q, SLOT(_q_endAnimatedOperation()));
 #endif //QT_NO_ANIMATION
 }
diff --git a/src/widgets/styles/qcommonstyle.cpp b/src/widgets/styles/qcommonstyle.cpp
index 477d180a2b..0c1cf0ec6e 100644
--- a/src/widgets/styles/qcommonstyle.cpp
+++ b/src/widgets/styles/qcommonstyle.cpp
@@ -5246,6 +5246,8 @@ int QCommonStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget
         break;
 #endif
     case SH_Widget_Animate:
+    // TODO Qt6: move this code in the SH_Widget_Animation_Duration case
+    // and replace false with 0 and true with 200.
 #ifndef QT_NO_TREEVIEW
         if (qobject_cast<const QTreeView*>(widget)) {
             ret = false;
@@ -5266,6 +5268,9 @@ int QCommonStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget
     case SH_TitleBar_ShowToolTipsOnButtons:
         ret = true;
         break;
+    case SH_Widget_Animation_Duration:
+        ret = styleHint(SH_Widget_Animate, opt, widget, hret) ? 200 : 0;
+        break;
     default:
         ret = 0;
         break;
diff --git a/src/widgets/styles/qstyle.cpp b/src/widgets/styles/qstyle.cpp
index 7e37d10cb5..0350d5e1a5 100644
--- a/src/widgets/styles/qstyle.cpp
+++ b/src/widgets/styles/qstyle.cpp
@@ -1972,9 +1972,7 @@ void QStyle::drawItemPixmap(QPainter *painter, const QRect &rect, int alignment,
            a tooltip is shown (notice: shown, not hidden). When a new wake isn't needed, a user-requested tooltip
            will be shown nearly instantly.
 
-    \value SH_Widget_Animate Determines if the widget should show animations or not, for example
-           a transition between checked and unchecked statuses in a checkbox.
-           This enum value has been introduced in Qt 5.2.
+    \value SH_Widget_Animate Deprecated. Use \l{SH_Widget_Animation_Duration} instead.
 
     \value SH_Splitter_OpaqueResize Determines if resizing is opaque
            This enum value has been introduced in Qt 5.2
@@ -1992,6 +1990,11 @@ void QStyle::drawItemPixmap(QPainter *painter, const QRect &rect, int alignment,
            The Mac style, for example, sets this to false.
            This enum value has been introduced in Qt 5.10.
 
+    \value SH_Widget_Animation_Duration
+           Determines how much an animation should last (in ms).
+           A value equal to zero means that the animations will be disabled.
+           This enum value has been introduced in Qt 5.10.
+
     \sa styleHint()
 */
 
diff --git a/src/widgets/styles/qstyle.h b/src/widgets/styles/qstyle.h
index ae5ddbcd1f..b4936a3e0a 100644
--- a/src/widgets/styles/qstyle.h
+++ b/src/widgets/styles/qstyle.h
@@ -738,6 +738,7 @@ public:
         SH_Menu_SubMenuDontStartSloppyOnLeave,
         SH_ItemView_ScrollMode,
         SH_TitleBar_ShowToolTipsOnButtons,
+        SH_Widget_Animation_Duration,
         // Add new style hint values here
 
         SH_CustomBase = 0xf0000000
diff --git a/src/widgets/styles/qstylesheetstyle.cpp b/src/widgets/styles/qstylesheetstyle.cpp
index 39a3e110f3..4fe697a32f 100644
--- a/src/widgets/styles/qstylesheetstyle.cpp
+++ b/src/widgets/styles/qstylesheetstyle.cpp
@@ -691,7 +691,8 @@ static const char knownStyleHints[][45] = {
     "titlebar-unshade-icon",
     "toolbutton-popup-delay",
     "trash-icon",
-    "uparrow-icon"
+    "uparrow-icon",
+    "widget-animation-duration"
 };
 
 static const int numKnownStyleHints = sizeof(knownStyleHints)/sizeof(knownStyleHints[0]);
@@ -5325,6 +5326,7 @@ int QStyleSheetStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWi
         case SH_ItemView_ArrowKeysNavigateIntoChildren: s = QLatin1String("arrow-keys-navigate-into-children"); break;
         case SH_ItemView_PaintAlternatingRowColorsForEmptyArea: s = QLatin1String("paint-alternating-row-colors-for-empty-area"); break;
         case SH_TitleBar_ShowToolTipsOnButtons: s = QLatin1String("titlebar-show-tooltips-on-buttons"); break;
+        case SH_Widget_Animation_Duration: s = QLatin1String("widget-animation-duration"); break;
         default: break;
     }
     if (!s.isEmpty() && rule.hasStyleHint(s)) {
diff --git a/src/widgets/widgets/qtabbar_p.h b/src/widgets/widgets/qtabbar_p.h
index 7b14b636d1..6c5db02764 100644
--- a/src/widgets/widgets/qtabbar_p.h
+++ b/src/widgets/widgets/qtabbar_p.h
@@ -180,7 +180,7 @@ public:
 
     int indexAtPos(const QPoint &p) const;
 
-    inline bool isAnimated() const { Q_Q(const QTabBar); return q->style()->styleHint(QStyle::SH_Widget_Animate, 0, q); }
+    inline bool isAnimated() const { Q_Q(const QTabBar); return q->style()->styleHint(QStyle::SH_Widget_Animation_Duration, 0, q) > 0; }
     inline bool validIndex(int index) const { return index >= 0 && index < tabList.count(); }
     void setCurrentNextEnabledIndex(int offset);
 
diff --git a/src/widgets/widgets/qwidgetanimator.cpp b/src/widgets/widgets/qwidgetanimator.cpp
index d46d65546c..3a00999e57 100644
--- a/src/widgets/widgets/qwidgetanimator.cpp
+++ b/src/widgets/widgets/qwidgetanimator.cpp
@@ -91,13 +91,13 @@ void QWidgetAnimator::animate(QWidget *widget, const QRect &_final_geometry, boo
 
 #ifndef QT_NO_ANIMATION
     //If the QStyle has animations, animate
-    if (widget->style()->styleHint(QStyle::SH_Widget_Animate, 0, widget)) {
+    if (const int animationDuration = widget->style()->styleHint(QStyle::SH_Widget_Animation_Duration, 0, widget)) {
         AnimationMap::const_iterator it = m_animation_map.constFind(widget);
         if (it != m_animation_map.constEnd() && (*it)->endValue().toRect() == final_geometry)
             return;
 
         QPropertyAnimation *anim = new QPropertyAnimation(widget, "geometry", widget);
-        anim->setDuration(animate ? 200 : 0);
+        anim->setDuration(animate ? animationDuration : 0);
         anim->setEasingCurve(QEasingCurve::InOutQuad);
         anim->setEndValue(final_geometry);
         m_animation_map[widget] = anim;