From 1271197f70862fd1565039aff3b0e40665d3adde Mon Sep 17 00:00:00 2001
From: Eskil Abrahamsen Blomfeldt <eblomfel@trolltech.com>
Date: Fri, 22 May 2009 17:07:07 +0200
Subject: doc: Add documentation for QStaticText and QPainter::drawStaticText()

---
 src/gui/painting/qpainter.cpp | 28 +++++++++++++++++---
 src/gui/text/qstatictext.cpp  | 61 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index 00b462b..8ff93d2 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -5704,14 +5704,36 @@ void QPainter::drawText(const QPointF &p, const QString &str)
     drawText(p, str, 0, 0);
 }
 
-void QPainter::drawStaticText(const QPointF &p, const QStaticText &staticText)
+/*!    
+    \fn void QPainter::drawStaticText(const QPoint &position, const QStaticText &staticText)
+
+    \overload
+*/
+
+/*!    
+    \fn void QPainter::drawStaticText(int x, int y, const QStaticText &staticText)
+
+    \overload
+*/
+
+/*!
+    Draws the given \a staticText beginning at the given \a position. 
+
+    This function can be used to optimize drawing text if the text and its layout is updated 
+    seldomly.
+
+    \note To mirror the behavior of QPainter::drawText() the y-position will be used as the baseline
+    of the font if a size not set on \a staticText. If a size is set for \a staticText, \a position
+    is the top left corner of the clipping rectangle of the text.
+*/
+void QPainter::drawStaticText(const QPointF &position, const QStaticText &staticText)
 {
     const QStaticTextPrivate *staticText_d = QStaticTextPrivate::get(&staticText);
     QTextLayout *textLayout = staticText_d->textLayout;
 
     QSizeF size = staticText_d->size;
 
-    QRectF clipRect = size.isValid() ? QRectF(p, staticText_d->size) : QRectF();
+    QRectF clipRect = size.isValid() ? QRectF(position, staticText_d->size) : QRectF();
     QPainterPath oldClipPath;
     if (clipRect.isValid()) {
         oldClipPath = clipPath();
@@ -5722,7 +5744,7 @@ void QPainter::drawStaticText(const QPointF &p, const QStaticText &staticText)
         setClipPath(clipPath, Qt::IntersectClip);
     }
 
-    textLayout->draw(this, p, QVector<QTextLayout::FormatRange>(), clipRect);
+    textLayout->draw(this, position, QVector<QTextLayout::FormatRange>(), clipRect);
 
     if (clipRect.isValid())
         setClipPath(oldClipPath);    
diff --git a/src/gui/text/qstatictext.cpp b/src/gui/text/qstatictext.cpp
index 44cb799..1256427 100644
--- a/src/gui/text/qstatictext.cpp
+++ b/src/gui/text/qstatictext.cpp
@@ -44,6 +44,64 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QStaticText
+    \brief The QStaticText class enables optimized drawing of text when the text and its layout
+    is updated rarely.
+
+    \ingroup multimedia
+    \ingroup text
+    \mainclass
+
+    QStaticText provides a way to cache layout data for a block of text so that it can be drawn
+    more efficiently than by using QPainter::drawText() in which the layout information is 
+    recalculated with every call. 
+
+    The class primarily provides an optimization for cases where text is static over several paint
+    events. If the text or its layout is changed regularly, QPainter::drawText() is the more 
+    efficient alternative.
+
+    \code
+    class MyWidget: public QWidget
+    {
+    public:
+        MyWidget(QWidget *parent = 0) : QWidget(parent), m_staticText("This is static text")
+
+    protected:
+        void paintEvent(QPaintEvent *)
+        {
+            QPainter painter(this);
+            painter.drawStaticText(0, 0, m_staticText);
+        }
+
+    private:
+        QStaticText m_staticText;
+    };
+    \endcode
+
+    The QStaticText class can be used to mimic the behavior of QPainter::drawText() to a specific
+    point with no boundaries, and also when QPainter::drawText() is called with a bounding 
+    rectangle. 
+
+    If a bounding rectangle is not required, create a QStaticText object without setting a maximum 
+    size. The text will then occupy a single line. 
+
+    If you set a maximum size on the QStaticText object, this will bound the text. The text will
+    be formatted so that no line exceeds the given width. When the object is painted, it will 
+    be clipped vertically at the given height. The position of the text is decided by the argument
+    passed to QPainter::drawStaticText() and can change from call to call without affecting 
+    performance.
+
+    \sa QPainter::drawStaticText().
+*/
+
+/*!
+    \fn QStaticText::QStaticText(const QString &text, const QFont &font, const QSizeF &maximumSize)
+
+    Constructs a QStaticText object with the given \a text which is to be rendered in the given
+    \a font and bounded by the given \a maximumSize. If an invalid size is passed for \a maximumSize
+    the text will be unbounded.         
+*/
 QStaticText::QStaticText(const QString &text, const QFont &font, const QSizeF &sz)
     : d_ptr(new QStaticTextPrivate) 
 {
@@ -51,6 +109,9 @@ QStaticText::QStaticText(const QString &text, const QFont &font, const QSizeF &s
     d->init(text, font, sz);
 }
 
+/*!
+    Destroys the QStaticText.
+*/
 QStaticText::~QStaticText()
 {
     Q_D(QStaticText);
-- 
cgit v0.12