Add QTextOption/QTextEdit/QPlainTextEdit::tabStopDistance property

In Qt, we have QTextOption::tabStop, QTextEdit::tabStopWidth and
QPlainTextEdit::tabStopWidth.

Neither are very good names, since the tab stop is neither a
numerical value as in the former, nor does it have any dimensions
that can be measured, as in the latter. Vertical text advances
may also be supported by Qt at some point in the future, at
which point the name would make even less sense.

At the same time, we expose the actual type of the tab stop
distance as floating point in the QTextEdit and QPlainTextEdit
API instead of always rounding it to an int.

To avoid duplicating either of these APIs in Qt Quick, we
introduce tabStopDistance as the common term instead and deprecate
the old names.

[ChangeLog][Text] Introduced tabStopDistance property in
QTextOption, QTextEdit and QPlainTextEdit as replacement for
the inconsistently named tabStop and tabStopWidth properties.
QTextOption::tabStop, QTextEdit::tabStopWidth and
QPlainTextEdit::tabStopWidth have subsequently been deprecated.

Change-Id: Ib7e01387910cddb58adaaaadcd56c0e69edc4bc2
Reviewed-by: Paolo Angelelli <paolo.angelelli@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

5 files changed, 45 insertions, 12 deletions

diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index fb3c845e77..667c3b0fb5 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -7419,7 +7419,7 @@ void qt_format_text(const QFont &fnt, const QRectF &_r,
         if (option->flags() & QTextOption::IncludeTrailingSpaces)
             tf |= Qt::TextIncludeTrailingSpaces;
 
-        if (option->tabStop() >= 0 || !option->tabArray().isEmpty())
+        if (option->tabStopDistance() >= 0 || !option->tabArray().isEmpty())
             tf |= Qt::TextExpandTabs;
     }
 
@@ -7536,8 +7536,8 @@ start_lengthVariant:
         engine.option = *option;
     }
 
-    if (engine.option.tabStop() < 0 && tabstops > 0)
-        engine.option.setTabStop(tabstops);
+    if (engine.option.tabStopDistance() < 0 && tabstops > 0)
+        engine.option.setTabStopDistance(tabstops);
 
     if (engine.option.tabs().isEmpty() && ta) {
         QList<qreal> tabs;
diff --git a/src/gui/text/qtextdocument_p.cpp b/src/gui/text/qtextdocument_p.cpp
index 7341fa8e83..66e038122c 100644
--- a/src/gui/text/qtextdocument_p.cpp
+++ b/src/gui/text/qtextdocument_p.cpp
@@ -203,7 +203,7 @@ QTextDocumentPrivate::QTextDocumentPrivate()
     inContentsChange = false;
     blockCursorAdjustment = false;
 
-    defaultTextOption.setTabStop(80); // same as in qtextengine.cpp
+    defaultTextOption.setTabStopDistance(80); // same as in qtextengine.cpp
     defaultTextOption.setWrapMode(QTextOption::WrapAtWordBoundaryOrAnywhere);
     defaultCursorMoveStyle = Qt::LogicalMoveStyle;
 
diff --git a/src/gui/text/qtextengine.cpp b/src/gui/text/qtextengine.cpp
index a9d23d8e4b..faddb3552d 100644
--- a/src/gui/text/qtextengine.cpp
+++ b/src/gui/text/qtextengine.cpp
@@ -3043,7 +3043,7 @@ QFixed QTextEngine::calculateTabWidth(int item, QFixed x) const
             }
         }
     }
-    QFixed tab = QFixed::fromReal(option.tabStop());
+    QFixed tab = QFixed::fromReal(option.tabStopDistance());
     if (tab <= 0)
         tab = 80; // default
     tab *= dpiScale;
diff --git a/src/gui/text/qtextoption.cpp b/src/gui/text/qtextoption.cpp
index 87e31eeb2c..2a16f50f33 100644
--- a/src/gui/text/qtextoption.cpp
+++ b/src/gui/text/qtextoption.cpp
@@ -144,7 +144,7 @@ QTextOption &QTextOption::operator=(const QTextOption &o)
     Sets the tab positions for the text layout to those specified by
     \a tabStops.
 
-    \sa tabArray(), setTabStop(), setTabs()
+    \sa tabArray(), setTabStopDistance(), setTabs()
 */
 void QTextOption::setTabArray(const QList<qreal> &tabStops)
 {
@@ -332,22 +332,45 @@ QList<QTextOption::Tab> QTextOption::tabs() const
   \sa flags()
 */
 
+#if QT_DEPRECATED_SINCE(5, 10)
 /*!
   \fn qreal QTextOption::tabStop() const
+  \deprecated in Qt 5.10. Use tabStopDistance() instead.
 
   Returns the distance in device units between tab stops.
   Convenient function for the above method
 
-  \sa setTabStop(), tabArray(), setTabs(), tabs()
+  \sa setTabStopDistance(), tabArray(), setTabs(), tabs()
 */
 
 /*!
   \fn void QTextOption::setTabStop(qreal tabStop)
+  \deprecated in Qt 5.10. Use setTabStopDistance() instead.
 
   Sets the default distance in device units between tab stops to the value specified
   by \a tabStop.
 
-  \sa tabStop(), setTabArray(), setTabs(), tabs()
+  \sa tabStopDistance(), setTabArray(), setTabs(), tabs()
+*/
+#endif
+
+/*!
+  \fn qreal QTextOption::tabStopDistance() const
+  \since 5.10
+
+  Returns the distance in device units between tab stops.
+
+  \sa setTabStopDistance(), tabArray(), setTabs(), tabs()
+*/
+
+/*!
+  \fn void QTextOption::setTabStopDistance(qreal tabStopDistance)
+  \since 5.10
+
+  Sets the default distance in device units between tab stops to the value specified
+  by \a tabStopDistance.
+
+  \sa tabStopDistance(), setTabArray(), setTabs(), tabs()
 */
 
 /*!
@@ -426,7 +449,7 @@ QList<QTextOption::Tab> QTextOption::tabs() const
   \fn void setTabs(const QList<Tab> &tabStops)
   Set the Tab properties to \a tabStops.
 
-  \sa tabStop(), tabs()
+  \sa tabStopDistance(), tabs()
 */
 
 /*!
@@ -434,7 +457,7 @@ QList<QTextOption::Tab> QTextOption::tabs() const
   \fn QList<QTextOption::Tab> QTextOption::tabs() const
   Returns a list of tab positions defined for the text layout.
 
-  \sa tabStop(), setTabs(), setTabStop()
+  \sa tabStopDistance(), setTabs(), setTabStop()
 */
 
 
diff --git a/src/gui/text/qtextoption.h b/src/gui/text/qtextoption.h
index 9ef9cee9bb..8b57278633 100644
--- a/src/gui/text/qtextoption.h
+++ b/src/gui/text/qtextoption.h
@@ -117,8 +117,13 @@ public:
     inline void setFlags(Flags flags);
     inline Flags flags() const { return Flags(f); }
 
-    inline void setTabStop(qreal tabStop);
-    inline qreal tabStop() const { return tab; }
+#if QT_DEPRECATED_SINCE(5, 10)
+    QT_DEPRECATED inline void setTabStop(qreal tabStop);
+    QT_DEPRECATED inline qreal tabStop() const { return tabStopDistance(); }
+#endif
+
+    inline void setTabStopDistance(qreal tabStopDistance);
+    inline qreal tabStopDistance() const { return tab; }
 
     void setTabArray(const QList<qreal> &tabStops);
     QList<qreal> tabArray() const;
@@ -149,7 +154,12 @@ inline void QTextOption::setAlignment(Qt::Alignment aalignment)
 inline void QTextOption::setFlags(Flags aflags)
 { f = aflags; }
 
+#if QT_DEPRECATED_SINCE(5, 10)
 inline void QTextOption::setTabStop(qreal atabStop)
+{ setTabStopDistance(atabStop); }
+#endif
+
+inline void QTextOption::setTabStopDistance(qreal atabStop)
 { tab = atabStop; }
 
 QT_END_NAMESPACE