Doc: Update text that refers to deprecated member function width()

* Add see also links from the deprecated function to the replacement.
* Change introduction text to reflect new function name rather than the
  old and deprecated width().
* Change see also and inline references to width(), so that they now
  refer to horizontalAdvance().

Task-number: QTBUG-65141
Change-Id: Iadfbc517e5df96e32058516f8795bd210cc4c5e4
Reviewed-by: Nico Vertriest <nico.vertriest@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

1 files changed, 37 insertions, 33 deletions

diff --git a/src/gui/text/qfontmetrics.cpp b/src/gui/text/qfontmetrics.cpp
index d3e4f11e8c..b7a3066f3a 100644
--- a/src/gui/text/qfontmetrics.cpp
+++ b/src/gui/text/qfontmetrics.cpp
@@ -106,12 +106,12 @@ extern void qt_format_text(const QFont& font, const QRectF &_r,
     These are by necessity slow, and we recommend avoiding them if
     possible.
 
-    For each character, you can get its width(), leftBearing() and
-    rightBearing() and find out whether it is in the font using
+    For each character, you can get its horizontalAdvance(), leftBearing(),
+    and rightBearing(), and find out whether it is in the font using
     inFont(). You can also treat the character as a string, and use
     the string functions on it.
 
-    The string functions include width(), to return the width of a
+    The string functions include horizontalAdvance(), to return the width of a
     string in pixels (or points, for a printer), boundingRect(), to
     return a rectangle large enough to contain the rendered string,
     and size(), to return the size of that rectangle.
@@ -464,9 +464,9 @@ bool QFontMetrics::inFontUcs4(uint ucs4) const
     value is negative if the pixels of the character extend to the
     left of the logical origin.
 
-    See width() for a graphical description of this metric.
+    See horizontalAdvance() for a graphical description of this metric.
 
-    \sa rightBearing(), minLeftBearing(), width()
+    \sa rightBearing(), minLeftBearing(), horizontalAdvance()
 */
 int QFontMetrics::leftBearing(QChar ch) const
 {
@@ -495,11 +495,11 @@ int QFontMetrics::leftBearing(QChar ch) const
     The right bearing is the left-ward distance of the right-most
     pixel of the character from the logical origin of a subsequent
     character. This value is negative if the pixels of the character
-    extend to the right of the width() of the character.
+    extend to the right of the horizontalAdvance() of the character.
 
-    See width() for a graphical description of this metric.
+    See horizontalAdvance() for a graphical description of this metric.
 
-    \sa leftBearing(), minRightBearing(), width()
+    \sa leftBearing(), minRightBearing(), horizontalAdvance()
 */
 int QFontMetrics::rightBearing(QChar ch) const
 {
@@ -535,7 +535,7 @@ int QFontMetrics::rightBearing(QChar ch) const
 
     \deprecated in Qt 5.11. Use horizontalAdvance() instead.
 
-    \sa boundingRect()
+    \sa boundingRect(), horizontalAdvance()
 */
 int QFontMetrics::width(const QString &text, int len) const
 {
@@ -601,7 +601,7 @@ int QFontMetrics::width(const QString &text, int len, int flags) const
     processing strings cannot be taken into account. When implementing
     an interactive text control, use QTextLayout instead.
 
-    \sa boundingRect()
+    \sa boundingRect(), horizontalAdvance()
 */
 int QFontMetrics::width(QChar ch) const
 {
@@ -751,7 +751,8 @@ int QFontMetrics::charWidth(const QString &text, int pos) const
 
     Note that the bounding rectangle may extend to the left of (0, 0),
     e.g. for italicized fonts, and that the width of the returned
-    rectangle might be different than what the width() method returns.
+    rectangle might be different than what the horizontalAdvance() method
+    returns.
 
     If you want to know the advance width of the string (to lay out
     a set of strings next to each other), use horizontalAdvance() instead.
@@ -762,7 +763,8 @@ int QFontMetrics::charWidth(const QString &text, int pos) const
     The height of the bounding rectangle is at least as large as the
     value returned by height().
 
-    \sa width(), height(), QPainter::boundingRect(), tightBoundingRect()
+    \sa horizontalAdvance(), height(), QPainter::boundingRect(),
+        tightBoundingRect()
 */
 QRect QFontMetrics::boundingRect(const QString &text) const
 {
@@ -790,7 +792,7 @@ QRect QFontMetrics::boundingRect(const QString &text) const
     \warning The width of the returned rectangle is not the advance width
     of the character. Use boundingRect(const QString &) or horizontalAdvance() instead.
 
-    \sa width()
+    \sa horizontalAdvance()
 */
 QRect QFontMetrics::boundingRect(QChar ch) const
 {
@@ -864,7 +866,7 @@ QRect QFontMetrics::boundingRect(QChar ch) const
     fontHeight() and lineSpacing() are used to calculate the height,
     rather than individual character heights.
 
-    \sa width(), QPainter::boundingRect(), Qt::Alignment
+    \sa horizontalAdvance(), QPainter::boundingRect(), Qt::Alignment
 */
 QRect QFontMetrics::boundingRect(const QRect &rect, int flags, const QString &text, int tabStops,
                                  int *tabArray) const
@@ -920,7 +922,8 @@ QSize QFontMetrics::size(int flags, const QString &text, int tabStops, int *tabA
 
     Note that the bounding rectangle may extend to the left of (0, 0),
     e.g. for italicized fonts, and that the width of the returned
-    rectangle might be different than what the width() method returns.
+    rectangle might be different than what the horizontalAdvance() method
+    returns.
 
     If you want to know the advance width of the string (to lay out
     a set of strings next to each other), use horizontalAdvance() instead.
@@ -930,7 +933,7 @@ QSize QFontMetrics::size(int flags, const QString &text, int tabStops, int *tabA
 
     \warning Calling this method is very slow on Windows.
 
-    \sa width(), height(), boundingRect()
+    \sa horizontalAdvance(), height(), boundingRect()
 */
 QRect QFontMetrics::tightBoundingRect(const QString &text) const
 {
@@ -1079,12 +1082,12 @@ qreal QFontMetrics::fontDpi() const
     These are by necessity slow, and we recommend avoiding them if
     possible.
 
-    For each character, you can get its width(), leftBearing() and
-    rightBearing() and find out whether it is in the font using
+    For each character, you can get its horizontalAdvance(), leftBearing(), and
+    rightBearing(), and find out whether it is in the font using
     inFont(). You can also treat the character as a string, and use
     the string functions on it.
 
-    The string functions include width(), to return the width of a
+    The string functions include horizontalAdvance(), to return the width of a
     string in pixels (or points, for a printer), boundingRect(), to
     return a rectangle large enough to contain the rendered string,
     and size(), to return the size of that rectangle.
@@ -1434,9 +1437,9 @@ bool QFontMetricsF::inFontUcs4(uint ucs4) const
     value is negative if the pixels of the character extend to the
     left of the logical origin.
 
-    See width() for a graphical description of this metric.
+    See horizontalAdvance() for a graphical description of this metric.
 
-    \sa rightBearing(), minLeftBearing(), width()
+    \sa rightBearing(), minLeftBearing(), horizontalAdvance()
 */
 qreal QFontMetricsF::leftBearing(QChar ch) const
 {
@@ -1465,11 +1468,11 @@ qreal QFontMetricsF::leftBearing(QChar ch) const
     The right bearing is the left-ward distance of the right-most
     pixel of the character from the logical origin of a subsequent
     character. This value is negative if the pixels of the character
-    extend to the right of the width() of the character.
+    extend to the right of the horizontalAdvance() of the character.
 
-    See width() for a graphical description of this metric.
+    See horizontalAdvance() for a graphical description of this metric.
 
-    \sa leftBearing(), minRightBearing(), width()
+    \sa leftBearing(), minRightBearing(), horizontalAdvance()
 */
 qreal QFontMetricsF::rightBearing(QChar ch) const
 {
@@ -1504,7 +1507,7 @@ qreal QFontMetricsF::rightBearing(QChar ch) const
 
     \deprecated in Qt 5.11. Use horizontalAdvance() instead.
 
-    \sa boundingRect()
+    \sa boundingRect(), horizontalAdvance()
 */
 qreal QFontMetricsF::width(const QString &text) const
 {
@@ -1535,7 +1538,7 @@ qreal QFontMetricsF::width(const QString &text) const
     processing strings cannot be taken into account. When implementing
     an interactive text control, use QTextLayout instead.
 
-    \sa boundingRect()
+    \sa boundingRect(), horizontalAdvance()
 */
 qreal QFontMetricsF::width(QChar ch) const
 {
@@ -1581,7 +1584,7 @@ qreal QFontMetricsF::horizontalAdvance(const QString &text, int length) const
     ch.
 
     Some of the metrics are described in the image to the right. The
-    central dark rectangles cover the logical width() of each
+    central dark rectangles cover the logical horizontalAdvance() of each
     character. The outer pale rectangles cover the leftBearing() and
     rightBearing() of each character. Notice that the bearings of "f"
     in this particular font are both negative, while the bearings of
@@ -1632,7 +1635,7 @@ qreal QFontMetricsF::horizontalAdvance(QChar ch) const
 
     Note that the bounding rectangle may extend to the left of (0, 0),
     e.g. for italicized fonts, and that the width of the returned
-    rectangle might be different than what the width() method returns.
+    rectangle might be different than what the horizontalAdvance() method returns.
 
     If you want to know the advance width of the string (to lay out
     a set of strings next to each other), use horizontalAdvance() instead.
@@ -1643,7 +1646,7 @@ qreal QFontMetricsF::horizontalAdvance(QChar ch) const
     The height of the bounding rectangle is at least as large as the
     value returned height().
 
-    \sa width(), height(), QPainter::boundingRect()
+    \sa horizontalAdvance(), height(), QPainter::boundingRect()
 */
 QRectF QFontMetricsF::boundingRect(const QString &text) const
 {
@@ -1669,7 +1672,7 @@ QRectF QFontMetricsF::boundingRect(const QString &text) const
     Note that the rectangle usually extends both above and below the
     base line.
 
-    \sa width()
+    \sa horizontalAdvance()
 */
 QRectF QFontMetricsF::boundingRect(QChar ch) const
 {
@@ -1746,7 +1749,7 @@ QRectF QFontMetricsF::boundingRect(QChar ch) const
     fontHeight() and lineSpacing() are used to calculate the height,
     rather than individual character heights.
 
-    \sa width(), QPainter::boundingRect(), Qt::Alignment
+    \sa horizontalAdvance(), QPainter::boundingRect(), Qt::Alignment
 */
 QRectF QFontMetricsF::boundingRect(const QRectF &rect, int flags, const QString& text,
                                    int tabStops, int *tabArray) const
@@ -1805,7 +1808,8 @@ QSizeF QFontMetricsF::size(int flags, const QString &text, int tabStops, int *ta
 
     Note that the bounding rectangle may extend to the left of (0, 0),
     e.g. for italicized fonts, and that the width of the returned
-    rectangle might be different than what the width() method returns.
+    rectangle might be different than what the horizontalAdvance() method
+    returns.
 
     If you want to know the advance width of the string (to lay out
     a set of strings next to each other), use horizontalAdvance() instead.
@@ -1815,7 +1819,7 @@ QSizeF QFontMetricsF::size(int flags, const QString &text, int tabStops, int *ta
 
     \warning Calling this method is very slow on Windows.
 
-    \sa width(), height(), boundingRect()
+    \sa horizontalAdvance(), height(), boundingRect()
 */
 QRectF QFontMetricsF::tightBoundingRect(const QString &text) const
 {