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>

3 files changed, 56 insertions, 7 deletions

diff --git a/src/gui/doc/images/qpainter-text-bounds.png b/src/gui/doc/images/qpainter-text-bounds.png
new file mode 100644
index 0000000000..f92b8502f4
--- /dev/null
+++ b/src/gui/doc/images/qpainter-text-bounds.png
diff --git a/src/gui/doc/snippets/code/src_gui_painting_qpainter.cpp b/src/gui/doc/snippets/code/src_gui_painting_qpainter.cpp
index 1367ab2f8c..6d0308b1e9 100644
--- a/src/gui/doc/snippets/code/src_gui_painting_qpainter.cpp
+++ b/src/gui/doc/snippets/code/src_gui_painting_qpainter.cpp
@@ -257,3 +257,23 @@ glDisable(GL_SCISSOR_TEST);
 
 painter.endNativePainting();
 //! [21]
+
+//! [drawText]
+QPainter painter(this);
+QFont font = painter.font();
+font.setPixelSize(48);
+painter.setFont(font);
+
+const QRect rectangle = QRect(0, 0, 100, 50);
+QRect boundingRect;
+painter.drawText(rectangle, 0, tr("Hello"), &boundingRect);
+
+QPen pen = painter.pen();
+pen.setStyle(Qt::DotLine);
+painter.setPen(pen);
+painter.drawRect(boundingRect.adjusted(0, 0, -pen.width(), -pen.width()));
+
+pen.setStyle(Qt::DashLine);
+painter.setPen(pen);
+painter.drawRect(rectangle.adjusted(0, 0, -pen.width(), -pen.width()));
+//! [drawText]
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