Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# QTextLayout Class Reference

The QTextLayout class is used to lay out and paint a single paragraph of text. More...

    #include <QTextLayout>

- List of all members, including inherited members

### Public Types

- enum CursorMode { SkipCharacters, SkipWords }
- enum LineBreakStrategy { AtWordBoundaries, AtCharBoundaries }

### Public Functions

- QTextLayout ()
- QTextLayout ( const QString & string )
- QTextLayout ( const QString & string, QPainter * p )
- QTextLayout ( const QString & string, const QFont & fnt )
- QTextLayout ( const QTextBlock & block )
- ~QTextLayout ()
- QRect boundingRect () const
- void clearLines ()
- QTextLine createLine ()
- void draw ( QPainter * p, const QPoint & pos, int cursorPos, const QVector<Selection> & selections ) const
- QTextLine findLine ( int pos ) const
- QTextLine lineAt ( int i ) const
- int maximumWidth () const
- int minimumWidth () const
- int nextCursorPosition ( int oldPos, CursorMode mode = SkipCharacters ) const
- int numLines () const
- QPoint position () const
- int previousCursorPosition ( int oldPos, CursorMode mode = SkipCharacters ) const
- void setDirection ( QChar::Direction direction )
- void setPosition ( const QPoint & p )
- void setText ( const QString & string )
- QString text () const
- void useDesignMetrics ( bool b )
- bool usesDesignMetrics () const
- bool validCursorPosition ( int pos ) const

## Detailed Description

The QTextLayout class is used to lay out and paint a single paragraph of text.

It offers most features expected from a modern text layout engine, including Unicode compliant rendering, line breaking and handling of cursor positioning. It can also produce and render device independent layout, something that is important for WYSIWYG applications.

The class has a rather low level API and unless you intend to implement you own text rendering for some specialized widget, you probably won't need to use it directly.

QTextLayout can currently deal with plain text and rich text paragraphs that are part of a QTextDocument.

QTextLayout can be used to create a sequence of QTextLine's with given widths and can position them independently on the screen. Once the layout is done, these lines can be drawn on a paint device.

Here's some pseudo code that presents the layout phase:

        int leading = fontMetrics.leading();
        int height = 0;
        int widthUsed = 0;
        textLayout.clearLines();
        while (1) {
            QTextLine line = textLayout.createLine();
            if (!line.isValid())
                break;

            line.layout(lineWidth);
            height += leading;
            line.setPosition(QPoint(0, height));
            height += line.height();
            widthUsed = qMax(widthUsed, line.textWidth());
        }

And here's some pseudo code that presents the painting phase:

        for (int i = 0; i < textLayout.numLines(); ++i) {
            QTextLine line = textLayout.lineAt(i);
            line.draw(painter, rect.x() + xoffset + line.x(), rect.y() + yoffset);
        }

The text layout's text is set in the constructor or with setText(). The layout can be seen as a sequence of QTextLine objects; use lineAt() or findLine() to get a QTextLine, createLine() to create one and clearLines() to remove them. For a given position in the text you can find a valid cursor position with validCursorPosition(), nextCursorPosition(), and previousCursorPosition(). The layout itself can be positioned with setPosition(); it has a boundingRect(), and a minimumWidth() and a maximumWidth(). A text layout can be drawn on a painter device using draw().

## Member Type Documentation

### enum QTextLayout::CursorMode

`QTextLayout::SkipCharacters` |
`QTextLayout::SkipWords` |

### enum QTextLayout::LineBreakStrategy

`QTextLayout::AtWordBoundaries` |
`QTextLayout::AtCharBoundaries` |

## Member Function Documentation

### QTextLayout::QTextLayout ()

Constructs an empty text layout.

See also setText().

### QTextLayout::QTextLayout ( const QString & string )

Constructs a text layout to lay out the given string.

### QTextLayout::QTextLayout ( const QString & string, QPainter * p )

Constructs a text layout to lay out the given string.

All the metric and layout calculations will be done in terms of the painter, p.

### QTextLayout::QTextLayout ( const QString & string, const QFont & fnt )

Constructs a text layout to lay out the given string using the font fnt.

### QTextLayout::QTextLayout ( const QTextBlock & block )

Constructs a text layout to lay out the given block.

### QTextLayout::~QTextLayout ()

Destructs the layout.

### QRect QTextLayout::boundingRect () const

The smallest rectangle that contains all the lines in the layout.

### void QTextLayout::clearLines ()

Clears the layout information stored in the layout, and begins a new layout process.

### QTextLine QTextLayout::createLine ()

Creates a new text line to be laid out.

The text layout creates a new line object that starts after the last layouted line (or at the beginning of the contained text if no line has been layouted up to now).

The line is still empty and you need to call layout() on the line to fill it with text. After the layout() call a new line can be created and filled again. Repeating this process will layout the whole block of text contained in the QTextLayout. If there is no text left to be layouted, the retuned QTextLine will not be valid (ie. isValid() will return false).

### void QTextLayout::draw ( QPainter * p, const QPoint & pos, int cursorPos, const QVector<Selection> & selections ) const

Draws the whole layout on painter p at point pos with the given cursorPos with the given selections (which may be empty).

### QTextLine QTextLayout::findLine ( int pos ) const

Returns the line that contains the cursor position pos.

See also validCursorPosition() and lineAt().

### QTextLine QTextLayout::lineAt ( int i ) const

Returns the i-th line of text in this text layout.

See also numLines() and findLine().

### int QTextLayout::maximumWidth () const

The maximum width the layout could expand to; this is essentially the width of the entire text.

Warning: This function only returns a valid value after the layout has been done.

See also minimumWidth().

### int QTextLayout::minimumWidth () const

The minimum width the layout needs. This is the width of the layout's smallest non-breakable sub-string.

Warning: This function only returns a valid value after the layout has been done.

See also maximumWidth().

### int QTextLayout::nextCursorPosition ( int oldPos, CursorMode mode = SkipCharacters ) const

Returns the next valid cursor position after oldPos that respects the given cursor mode.

See also validCursorPosition() and previousCursorPosition().

### int QTextLayout::numLines () const

Returns the number of lines in this text layout.

See also lineAt().

### QPoint QTextLayout::position () const

The global position of the layout. This is independent of the bounding rectangle and of the layout process.

See also setPosition().

### int QTextLayout::previousCursorPosition ( int oldPos, CursorMode mode = SkipCharacters ) const

Returns the first valid cursor position before oldPos that respects the given cursor mode.

See also validCursorPosition() and nextCursorPosition().

### void QTextLayout::setDirection ( QChar::Direction direction )

Sets the direction of the text flow in the layout.

### void QTextLayout::setPosition ( const QPoint & p )

Moves the text layout to point p.

See also position().

### void QTextLayout::setText ( const QString & string )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the layout's text to the given string. The layout is invalidated and must be laid out again.

See also text().

### QString QTextLayout::text () const

Returns the layout's text.

See also setText().

### void QTextLayout::useDesignMetrics ( bool b )

If b is true then the layout will use design metrics for its layout; otherwise it will use the metrics of the paint device (which is the default behavior).

See also usesDesignMetrics().

### bool QTextLayout::usesDesignMetrics () const

Returns true if this layout uses design rather than device metrics; otherwise returns false.

See also useDesignMetrics().

### bool QTextLayout::validCursorPosition ( int pos ) const

Returns true if position pos is a valid cursor position.

In a Unicode context some positions in the text are not valid cursor positions, because the position is inside a Unicode surrogate or a grapheme cluster.

A grapheme cluster is a sequence of two or more Unicode characters that form one indivisible entity on the screen. For example the latin character `Ä' can be represented in Unicode by two characters, `A' (0x41), and the combining diaresis (0x308). A text cursor can only validly be positioned before or after these two characters, never between them since that wouldn't make sense. In indic languages every syllable forms a grapheme cluster.