Clarify QPainter::drawText() documentation.

The difference between rectangle and boundingRect was not quite clear.
This patch adds a snippet with a corresponding image, in order to
illustrate the difference.

Change-Id: Icb1fe737788cc93f1c5baa16bc0e04b8ec728f3a
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@theqtcompany.com>

1 files changed, 36 insertions, 7 deletions

diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index 973c9da96c..213ecc5f8e 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -5966,8 +5966,17 @@ void QPainter::drawText(const QRect &r, int flags, const QString &str, QRect *br
     \endtable
 
     The \a boundingRect (if not null) is set to the what the bounding rectangle
-    should be in order to enclose the whole text. The \a flags argument is a bitwise
-    OR of the following flags:
+    should be in order to enclose the whole text. For example, in the following
+    image, the dotted line represents \a boundingRect as calculated by the
+    function, and the dashed line represents \a rectangle:
+
+    \table 100%
+    \row
+    \li \inlineimage qpainter-text-bounds.png
+    \li \snippet code/src_gui_painting_qpainter.cpp drawText
+    \endtable
+
+    The \a flags argument is a bitwise OR of the following flags:
 
     \list
     \li Qt::AlignLeft
@@ -6016,8 +6025,18 @@ void QPainter::drawText(const QRectF &r, int flags, const QString &str, QRectF *
     \overload
 
     Draws the given \a text within the provided \a rectangle according
-    to the specified \a flags. The \a boundingRect (if not null) is set to
-    the what the bounding rectangle should be in order to enclose the whole text.
+    to the specified \a flags.
+
+    The \a boundingRect (if not null) is set to the what the bounding rectangle
+    should be in order to enclose the whole text. For example, in the following
+    image, the dotted line represents \a boundingRect as calculated by the
+    function, and the dashed line represents \a rectangle:
+
+    \table 100%
+    \row
+    \li \inlineimage qpainter-text-bounds.png
+    \li \snippet code/src_gui_painting_qpainter.cpp drawText
+    \endtable
 
     By default, QPainter draws text anti-aliased.
 
@@ -6050,9 +6069,19 @@ void QPainter::drawText(const QRectF &r, int flags, const QString &str, QRectF *
     Draws the given \a text within the rectangle with origin (\a{x},
     \a{y}), \a width and \a height.
 
-    The \a boundingRect (if not null) is set to the actual bounding
-    rectangle of the output.  The \a flags argument is a bitwise OR of
-    the following flags:
+    The \a boundingRect (if not null) is set to the what the bounding rectangle
+    should be in order to enclose the whole text. For example, in the following
+    image, the dotted line represents \a boundingRect as calculated by the
+    function, and the dashed line represents the rectangle defined by
+    \a x, \a y, \a width and \a height:
+
+    \table 100%
+    \row
+    \li \inlineimage qpainter-text-bounds.png
+    \li \snippet code/src_gui_painting_qpainter.cpp drawText
+    \endtable
+
+    The \a flags argument is a bitwise OR of the following flags:
 
     \list
     \li Qt::AlignLeft