From 817f307a18d28143a1e8234f3846d019589c9d7a Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Thu, 8 Sep 2022 12:26:03 +0200 Subject: [PATCH] doc: Clarify the term advance width The QFontMetrics documentation has been wrongly stating that the the horizontalAdvance() gives the width of a string, dating back to when the function was misnamed as width(). This can cause issues e.g. when using the value as input to eliding or clipping, since the advance may be smaller than what is actually drawn. This tries to clarify the term a bit. Task-number: QTBUG-90036 Change-Id: I8ed82fa14fe26c2a20cdbee9f2097a0aa4cc3925 Reviewed-by: Lars Knoll --- .../snippets/code/src_gui_text_qfontmetrics.cpp | 4 ++-- src/gui/text/qfontmetrics.cpp | 14 +++++++++++--- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/gui/doc/snippets/code/src_gui_text_qfontmetrics.cpp b/src/gui/doc/snippets/code/src_gui_text_qfontmetrics.cpp index 33a82f8dd1..4650ad8d8f 100644 --- a/src/gui/doc/snippets/code/src_gui_text_qfontmetrics.cpp +++ b/src/gui/doc/snippets/code/src_gui_text_qfontmetrics.cpp @@ -9,7 +9,7 @@ void wrapper0() { //! [0] QFont font("times", 24); QFontMetrics fm(font); -int pixelsWide = fm.horizontalAdvance("What's the width of this text?"); +int pixelsWide = fm.horizontalAdvance("What's the advance width of this text?"); int pixelsHigh = fm.height(); //! [0] @@ -22,7 +22,7 @@ void wrapper1() { //! [1] QFont font("times", 24); QFontMetricsF fm(font); -qreal pixelsWide = fm.horizontalAdvance("What's the width of this text?"); +qreal pixelsWide = fm.horizontalAdvance("What's the advance width of this text?"); qreal pixelsHigh = fm.height(); //! [1] diff --git a/src/gui/text/qfontmetrics.cpp b/src/gui/text/qfontmetrics.cpp index 7997f643ab..7e6af54a56 100644 --- a/src/gui/text/qfontmetrics.cpp +++ b/src/gui/text/qfontmetrics.cpp @@ -75,11 +75,19 @@ extern void qt_format_text(const QFont& font, const QRectF &_r, inFont(). You can also treat the character as a string, and use the string functions on it. - 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, + The string functions include horizontalAdvance(), to return the advance + 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. + \note The advance width can be different from the width of the actual + rendered text. It refers to the distance from the origin of the string to + where you would append additional characters. As text may have overhang + (in the case of an italic font for instance) or padding between + characters, the advance width can be either smaller or larger than the + actual rendering of the text. This is called the right bearing of the + text. + Example: \snippet code/src_gui_text_qfontmetrics.cpp 0