Rename QStaticText::setUseBackendOptimizations to setPerformanceHint()

Make the API more general and more readable by using a PerformanceHint
enum instead of an on/off-trigger for the OpenGL-specific caching.

Reviewed-by: Samuel

3 files changed, 45 insertions, 32 deletions

diff --git a/src/gui/text/qstatictext.cpp b/src/gui/text/qstatictext.cpp
index e3f1d26..a14b83f 100644
--- a/src/gui/text/qstatictext.cpp
+++ b/src/gui/text/qstatictext.cpp
@@ -117,6 +117,20 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \enum QStaticText::PerformanceHint
+
+    This enum the different performance hints that can be set on the QStaticText. These hints
+    can be used to indicate that the QStaticText should use additional caches, if possible,
+    to improve performance at the expense of memory. In particular, setting the performance hint
+    AggressiveCaching on the QStaticText will improve performance when using the OpenGL graphics
+    system or when drawing to a QGLWidget.
+
+    \value ModerateCaching Do basic caching for high performance at a low memory cost.
+    \value AggressiveCaching Use additional caching when available. This may improve performance
+           at a higher memory cost.
+*/
+
+/*!
     Constructs an empty QStaticText
 */
 QStaticText::QStaticText()    
@@ -268,41 +282,34 @@ QString QStaticText::text() const
 }
 
 /*!
-  Sets whether the QStaticText object should use optimizations specific to the paint engine
-  backend if they are available. If \a on is set to true, backend optimizations will be turned
-  on, otherwise they will be turned off. The default value is false.
-
-  If backend optimizations are on, the paint engine used to draw the static text is allowed to
-  store data in the object which will assist it in future calls to drawStaticText. In particular,
-  when using the opengl graphics system, or when painting on a QGLWidget, turning this flag on will
-  improve performance, but increase the memory footprint of the QStaticText object.
+  Sets the performance hint of the QStaticText. This hint can be used to customize how much
+  caching is done internally to improve performance.
 
-  The default value is false.
+  The default is QStaticText::ModerateCaching.
 
   \note This function will cause the layout of the text to be recalculated.
 
-  \sa useBackendOptimizations()
+  \sa performanceHint()
 */
-void QStaticText::setUseBackendOptimizations(bool on)
+void QStaticText::setPerformanceHint(PerformanceHint performanceHint)
 {
-    if ((!on && !data->useBackendOptimizations)
-        || (on && data->useBackendOptimizations))
+    if ((performanceHint == ModerateCaching && !data->useBackendOptimizations)
+        || (performanceHint == AggressiveCaching && data->useBackendOptimizations)) {
         return;
-
+    }
     detach();
-    data->useBackendOptimizations = on;
+    data->useBackendOptimizations = (performanceHint == AggressiveCaching);
     data->init();
 }
 
 /*!
-  Returns whether the QStaticText object should use optimizations specific to the paint engine
-  backend when possible. By default this setting is false.
+  Returns which performance hint is set for the QStaticText.
 
-  \sa setUseBackendOptimizations()
+  \sa setPerformanceHint()
 */
-bool QStaticText::useBackendOptimizations() const
+QStaticText::PerformanceHint QStaticText::performanceHint() const
 {
-    return data->useBackendOptimizations;
+    return data->useBackendOptimizations ? AggressiveCaching : ModerateCaching;
 }
 
 /*!
diff --git a/src/gui/text/qstatictext.h b/src/gui/text/qstatictext.h
index 8eeb068..652bb84 100644
--- a/src/gui/text/qstatictext.h
+++ b/src/gui/text/qstatictext.h
@@ -60,6 +60,11 @@ class QStaticTextPrivate;
 class Q_GUI_EXPORT QStaticText
 {    
 public:
+    enum PerformanceHint {
+        ModerateCaching,
+        AggressiveCaching
+    };
+
     QStaticText();
     QStaticText(const QString &text, const QSizeF &maximumSize = QSizeF());
     QStaticText(const QStaticText &other);
@@ -78,8 +83,8 @@ public:
 
     void prepare(const QTransform &matrix, const QFont &font);
 
-    void setUseBackendOptimizations(bool on);
-    bool useBackendOptimizations() const;
+    void setPerformanceHint(PerformanceHint performanceHint);
+    PerformanceHint performanceHint() const;
 
     QStaticText &operator=(const QStaticText &);
     bool operator==(const QStaticText &) const;
diff --git a/tests/auto/qstatictext/tst_qstatictext.cpp b/tests/auto/qstatictext/tst_qstatictext.cpp
index 69e9dc5..a99ae74 100644
--- a/tests/auto/qstatictext/tst_qstatictext.cpp
+++ b/tests/auto/qstatictext/tst_qstatictext.cpp
@@ -89,17 +89,18 @@ void tst_QStaticText::constructionAndDestruction()
     QStaticText text("My text");
 }
 
+Q_DECLARE_METATYPE(QStaticText::PerformanceHint)
 void tst_QStaticText::drawToPoint_data()
 {
-    QTest::addColumn<bool>("useBackendOptimizations");
+    QTest::addColumn<QStaticText::PerformanceHint>("performanceHint");
 
-    QTest::newRow("Without backend optimizations") << false;
-    QTest::newRow("With backend optimizations") << true;
+    QTest::newRow("Moderate caching") << QStaticText::ModerateCaching;
+    QTest::newRow("Aggressive caching") << QStaticText::AggressiveCaching;
 }
 
 void tst_QStaticText::drawToPoint()
 {
-    QFETCH(bool, useBackendOptimizations);
+    QFETCH(QStaticText::PerformanceHint, performanceHint);
 
     QPixmap imageDrawText(1000, 1000);
     imageDrawText.fill(Qt::white);
@@ -113,7 +114,7 @@ void tst_QStaticText::drawToPoint()
     {
         QPainter p(&imageDrawStaticText);
         QStaticText text("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
-        text.setUseBackendOptimizations(useBackendOptimizations);
+        text.setPerformanceHint(performanceHint);
         p.drawStaticText(QPointF(11, 12), text);
     }
 
@@ -122,15 +123,15 @@ void tst_QStaticText::drawToPoint()
 
 void tst_QStaticText::drawToRect_data()
 {
-    QTest::addColumn<bool>("useBackendOptimizations");
+    QTest::addColumn<QStaticText::PerformanceHint>("performanceHint");
 
-    QTest::newRow("Without backend optimizations") << false;
-    QTest::newRow("With backend optimizations") << true;
+    QTest::newRow("Moderate caching") << QStaticText::ModerateCaching;
+    QTest::newRow("Aggressive caching") << QStaticText::AggressiveCaching;
 }
 
 void tst_QStaticText::drawToRect()
 {
-    QFETCH(bool, useBackendOptimizations);
+    QFETCH(QStaticText::PerformanceHint, performanceHint);
 
     QPixmap imageDrawText(1000, 1000);
     imageDrawText.fill(Qt::white);
@@ -144,7 +145,7 @@ void tst_QStaticText::drawToRect()
     {
         QPainter p(&imageDrawStaticText);
         QStaticText text("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", QSizeF(10, 500));
-        text.setUseBackendOptimizations(useBackendOptimizations);
+        text.setPerformanceHint(performanceHint);
         p.drawStaticText(QPointF(11, 12), text);
     }