From e4d2a4bffa94bac919d2e0b0ad245b917b69b4d5 Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Tue, 16 Feb 2010 12:52:07 +0100 Subject: doc: Update documentation for QStaticText Make some smaller modifications, fixes and additions. Remove \internal because the API is public now, and add documentation for QPainter::drawStaticText() since this was missing. Reviewed-by: TrustMe --- src/gui/painting/qpainter.cpp | 23 +++++++++++++++++++++++ src/gui/text/qstatictext.cpp | 28 ++++++++++++++++------------ 2 files changed, 39 insertions(+), 12 deletions(-) diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp index e26a24d..2cb6915 100644 --- a/src/gui/painting/qpainter.cpp +++ b/src/gui/painting/qpainter.cpp @@ -5702,12 +5702,16 @@ void QPainter::drawImage(const QRectF &targetRect, const QImage &image, const QR \fn void QPainter::drawStaticText(const QPoint &position, const QStaticText &staticText) + \since 4.7 + \overload */ /*! \fn void QPainter::drawStaticText(int x, int y, const QStaticText &staticText) + \since 4.7 + \overload */ @@ -5733,6 +5737,25 @@ void QPainter::drawText(const QPointF &p, const QString &str) drawText(p, str, 0, 0); } +/*! + \since 4.7 + + Draws the given \a staticText at the given \a position. + + The text will be drawn using the font and the transformation set on the painter. If the + font and/or transformation set on the painter are different from the ones used to initialize + the layout of the QStaticText, then the layout will have to be recalculated. Use + QStaticText::prepare() to initialize \a staticText with the font and transformation with which + it will later be drawn. + + If \a position is not the same as when \a staticText was initialized, or when it was last drawn, + then there will be a slight overhead when translating the text to its new position. + + \note If the painter's transformation is not affine, then \a staticText will be drawn using regular + calls to drawText(), losing any potential performance improvement. + + \sa QStaticText +*/ void QPainter::drawStaticText(const QPointF &position, const QStaticText &staticText) { Q_D(QPainter); diff --git a/src/gui/text/qstatictext.cpp b/src/gui/text/qstatictext.cpp index 6cf7022..e3f1d26 100644 --- a/src/gui/text/qstatictext.cpp +++ b/src/gui/text/qstatictext.cpp @@ -50,7 +50,6 @@ QT_BEGIN_NAMESPACE /*! \class QStaticText - \internal \brief The QStaticText class enables optimized drawing of text when the text and its layout is updated rarely. \since 4.7 @@ -63,11 +62,13 @@ QT_BEGIN_NAMESPACE 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 and the transformations on - the painter are static over several paint events. If the text or its layout is changed - regularly, QPainter::drawText() is the more efficient alternative. Translating the painter - will not cause the layout of the text to be recalculated, but will cause a very small - performance impact on drawStaticText(). Altering any other parts of the painter's + The class primarily provides an optimization for cases where the text, its font and the + transformations on the painter are static over several paint events. If the text or its layout + is changed for every iteration, QPainter::drawText() is the more efficient alternative, since + the static text's layout would have to be recalculated to take the new state into consideration. + + Translating the painter will not cause the layout of the text to be recalculated, but will cause + a very small performance impact on drawStaticText(). Altering any other parts of the painter's transformation or the painter's font will cause the layout of the static text to be recalculated. This should be avoided as often as possible to maximize the performance benefit of using QStaticText. @@ -107,6 +108,11 @@ QT_BEGIN_NAMESPACE passed to QPainter::drawStaticText() and can change from call to call with a minimal impact on performance. + QStaticText will attempt to guess the format of the input text using Qt::mightBeRichText(). + To force QStaticText to display its contents as either plain text or rich text, use the + function QStaticText::setTextFormat() and pass in, respectively, Qt::PlainText and + Qt::RichText. + \sa QPainter::drawText(), QPainter::drawStaticText(), QTextLayout, QTextDocument */ @@ -119,11 +125,9 @@ QStaticText::QStaticText() } /*! - \fn QStaticText::QStaticText(const QString &text, const QFont &font, const QSizeF &maximumSize) + Constructs a QStaticText object with the given \a text and bounded by the given \a size. - 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. + If an invalid size is passed for \a size the text will be unbounded. */ QStaticText::QStaticText(const QString &text, const QSizeF &size) : data(new QStaticTextPrivate) @@ -302,11 +306,11 @@ bool QStaticText::useBackendOptimizations() const } /*! - Sets the maximum size of the QStaticText to \a maximumSize. + Sets the maximum size of the QStaticText to \a size. \note This function will cause the layout of the text to be recalculated. - \sa maximumSize() + \sa maximumSize(), size() */ void QStaticText::setMaximumSize(const QSizeF &size) { -- cgit v0.12