QTextLayout Class

The QTextLayout class is used to lay out and render text. More…

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

A QTextLayout breaks one paragraph of text into lines and draws them. It is what QTextDocument uses for each of its paragraphs, and it is there for code that draws text itself and needs to know where its lines and characters are: an editor of its own, or a delegate that wraps text.

The text has one font, and format ranges that change it for parts of the text: another family, size or weight, a color, an underline. The lines are made one by one, each as wide as the caller wants, which is how text flows around something:

QTextLayout layout(text, font);
layout.beginLayout();
qreal y = 0;
for (QTextLine line = layout.createLine(); line.isValid(); line = layout.createLine()) {
    line.setLineWidth(width);
    line.setPosition(QPointF(0, y));
    y += line.height();
}
layout.endLayout();

layout.draw(&painter, QPointF(10, 10));

See also QTextLine, QTextDocument and QTextCharFormat.

Differences from Qt

Member Type Documentation

enum QTextLayout::CursorMode

How far nextCursorPosition() and previousCursorPosition() go.

Member Function Documentation

QTextLayout::QTextLayout()

Constructs an empty layout.

[explicit] QTextLayout::QTextLayout(const QString &text)

Constructs a layout for the text text, in the default font.

QTextLayout::QTextLayout(const QString &text, const QFont &font, const QPaintDevice *paintdevice = nullptr)

Constructs a layout for the text text in the font font. paintdevice is not used: Nt measures text the same for every device.

QTextLayout::~QTextLayout()

Destroys the layout. Its lines are no longer valid.

void QTextLayout::beginLayout()

Starts a layout: discards the lines, so that createLine() starts at the beginning of the text.

See also endLayout() and createLine().

QRectF QTextLayout::boundingRect() const

Returns the smallest rectangle that has all the lines of the layout, in the coordinates of the layout.

void QTextLayout::clearFormats()

Removes the format ranges.

See also setFormats().

void QTextLayout::clearLayout()

Discards the lines of the layout.

See also beginLayout().

QTextLine QTextLayout::createLine()

Returns a new line for the text that the lines before it have not taken, or an invalid line if there is none left. An empty text has one line, which is empty. Give the line its width with QTextLine::setLineWidth() before the next line is created.

See also beginLayout() and lineAt().

void QTextLayout::draw(QPainter *p, const QPointF &pos, const QList<FormatRange> &selections = QList<FormatRange>(), const QRectF &clip = QRectF()) const

Draws the lines of the layout with p, with the top left corner of the layout at pos plus position(). The text has the color of the pen of the painter where no format range gives it another one. The formats in selections are drawn on top of the formats of the layout, which is how a selection is shown. With a valid clip, only the lines that touch it are drawn.

void QTextLayout::endLayout()

Ends the layout that beginLayout() started. Text that no line has taken does not show.

See also beginLayout().

QFont QTextLayout::font() const

Returns the font of the text, which format ranges change for parts of it.

See also setFont() and setFormats().

QList<FormatRange> QTextLayout::formats() const

Returns the format ranges of the text.

See also setFormats().

bool QTextLayout::isValidCursorPosition(int pos) const

Returns true if a cursor can stand at the position pos of the text: anywhere from 0 to the length of the text, except between the two halves of a surrogate pair.

QTextLine QTextLayout::lineAt(int i) const

Returns the line at position i, counted from 0, or an invalid line if there is none.

See also lineCount() and lineForTextPosition().

int QTextLayout::lineCount() const

Returns the number of lines of the layout.

See also lineAt().

QTextLine QTextLayout::lineForTextPosition(int pos) const

Returns the line that has the position pos of the text, or an invalid line if no line has it. The position after the last character belongs to the last line.

qreal QTextLayout::maximumWidth() const

Returns the width that the text takes when no line is broken: that of its longest paragraph line.

See also minimumWidth().

qreal QTextLayout::minimumWidth() const

Returns the width that the layout cannot go below without breaking a word: that of its longest word.

See also maximumWidth().

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

Returns the cursor position after oldPos: the next character, or with mode SkipWords the start of the next word. It is the length of the text if there is nothing after oldPos.

See also previousCursorPosition().

QPointF QTextLayout::position() const

Returns the position of the layout, which draw() adds to the position that it is given. A layout of a document has the position of its paragraph here.

See also setPosition().

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

Returns the cursor position before oldPos: the character before it, or with mode SkipWords the start of the word before it. It is 0 if there is nothing before oldPos.

See also nextCursorPosition().

void QTextLayout::setFont(const QFont &font)

Sets the font of the text to font. The lines are discarded.

See also font().

void QTextLayout::setFormats(const QList<FormatRange> &formats)

Sets the format ranges of the text to formats: each of them gives a part of the text its own font properties, colors, underline or strike out. Where ranges overlap, a later one goes on top of an earlier one. The lines are discarded.

See also formats() and clearFormats().

void QTextLayout::setPosition(const QPointF &p)

Sets the position of the layout to p.

See also position().

void QTextLayout::setText(const QString &string)

Sets the text to lay out to string. The lines are discarded, and so are the format ranges.

See also text().

void QTextLayout::setTextOption(const QTextOption &option)

Sets the alignment, the wrap mode and the tab stops of the layout to those of option. Lay the text out again afterwards.

See also textOption().

QString QTextLayout::text() const

Returns the text of the layout.

See also setText().

const QTextOption & QTextLayout::textOption() const

Returns the text option of the layout.

See also setTextOption().