QTextLayout Class

int leading = fontMetrics.leading();
qreal height = 0;
textLayout.setCacheEnabled(true);
textLayout.beginLayout();
while (true) {
    QTextLine line = textLayout.createLine();
    if (!line.isValid())
        break;

    line.setLineWidth(lineWidth);
    height += leading;
    line.setPosition(QPointF(0, height));
    height += line.height();
}
textLayout.endLayout();

QPainter painter(this);
textLayout.draw(&painter, QPoint(0, 0));

QPainter painter(this);
QFontMetrics fontMetrics = painter.fontMetrics();

int lineSpacing = fontMetrics.lineSpacing();
int y = 0;

QTextLayout textLayout(content, painter.font());
textLayout.beginLayout();
while (true) {
    QTextLine line = textLayout.createLine();

    if (!line.isValid())
        break;

    line.setLineWidth(width());
    const int nextLineY = y + lineSpacing;

    if (height() >= nextLineY + lineSpacing) {
        line.draw(&painter, QPoint(0, y));
        y = nextLineY;
    } else {
        const QString lastLine = content.mid(line.textStart());
        const QString elidedLastLine = fontMetrics.elidedText(lastLine, Qt::ElideRight, width());
        painter.drawText(QPoint(0, y + fontMetrics.ascent()), elidedLastLine);
        line = textLayout.createLine();
        break;
    }
}
textLayout.endLayout();

成员函数文档

QTextLayout::QTextLayout()

构建一个空的文本布局。

另请参阅 setText()。

QTextLayout::QTextLayout(const QString &text)

构建一个文本布局，用于排版给定的text 。

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

构建一个文本布局，用于根据指定的font 对给定的text 进行排版。

所有度量和布局计算都将基于绘制设备（paintdevice ）进行。如果paintdevice 为nullptr ，则计算将基于屏幕度量进行。

[noexcept] QTextLayout::~QTextLayout()

销毁布局。

void QTextLayout::beginLayout()

开始布局过程。

另请参阅 endLayout()。

QRectF QTextLayout::boundingRect() const

包含布局中所有线条的最小矩形。

bool QTextLayout::cacheEnabled() const

如果完整的布局信息已被缓存，则返回true ；否则返回false 。

另请参阅 setCacheEnabled()。

void QTextLayout::clearFormats()

清除文本布局支持的其他格式列表。

另请参阅 formats() 和setFormats()。

void QTextLayout::clearLayout()

清除布局中的行信息。调用此函数后，lineCount() 将返回 0。

QTextLine QTextLayout::createLine()

如果布局中有待插入的文本，则返回一个用于排版的新文本行；否则返回一个无效的文本行。

文本布局会创建一个新的行对象，该行从布局中的最后一行之后开始，如果布局为空，则从开头开始。布局维护一个内部光标，当调用QTextLine::setLineWidth()函数时，每行都会从光标位置开始填充文本。

一旦调用QTextLine::setLineWidth()，即可创建新行并填充文本。重复此过程将对QTextLayout 中包含的整个文本块进行排版。如果布局中已无文本可插入，则返回的QTextLine 将无效（isValid()将返回false）。

Qt::CursorMoveStyle QTextLayout::cursorMoveStyle() const

此QTextLayout 的游标移动样式。默认值为Qt::LogicalMoveStyle 。

另请参阅 setCursorMoveStyle()。

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

在画家p 上，将整个布局绘制到由pos 指定的位置。渲染后的布局包含给定的selections ，并在由clip 指定的矩形范围内进行裁剪。

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition, int width) const

使用当前画笔和指定的width ，在给定的position 处绘制文本光标，并使用指定的painter 。文本中的对应位置由cursorPosition 指定。

void QTextLayout::drawCursor(QPainter *painter, const QPointF &position, int cursorPosition) const

使用当前画笔，在指定坐标position 处绘制文本光标，并采用指定的painter 。文本中的对应位置由cursorPosition 指定。

void QTextLayout::endLayout()

结束版面处理过程。

另请参阅 beginLayout()。

QFont QTextLayout::font() const

返回当前用于布局的字体，如果未设置字体，则返回默认字体。

另请参阅 setFont()。

QList<QTextLayout::FormatRange> QTextLayout::formats() const

返回文本布局支持的其他格式列表。

另请参阅 setFormats() 和clearFormats()。

QList<QGlyphRun> QTextLayout::glyphRuns(int from = -1, int length = -1) const

返回本QTextLayout 中从位置from 开始的、与length 字符对应的所有字形索引和位置。该函数的执行成本较高，不应在对时间要求较高的场景中调用。

如果from 小于零，则字形序列将从布局中的第一个字符开始。如果length 小于零，则字形序列将从起始位置开始覆盖整个字符串。

另请参见 draw() 和QPainter::drawGlyphRun()。

[since 6.5] QList<QGlyphRun> QTextLayout::glyphRuns(int from, int length, QTextLayout::GlyphRunRetrievalFlags retrievalFlags) const

返回本QTextLayout 中从位置from 开始，所有与length 字符对应的字形索引和位置。此函数开销较大，不应在对时间敏感的上下文中调用。

如果from 小于零，则字形序列将从布局中的第一个字符开始。如果length 小于零，则该序列将从起始位置起覆盖整个字符串。

retrievalFlags 指定将从布局中检索QGlyphRun 的哪些属性。为尽量减少内存分配和内存消耗，应仅将后续需要访问的属性包含在此参数中。

该函数在 Qt 6.5 中引入。

另请参阅 draw() 和QPainter::drawGlyphRun()。

bool QTextLayout::isValidCursorPosition(int pos) const

如果位置pos 是有效光标位置，则返回true 。

在 Unicode 环境中，文本中的某些位置并非有效的光标位置，因为该位置位于 Unicode 代理字符或字形群内部。

字素簇是指由两个或更多 Unicode 字符组成的序列，它们在屏幕上构成一个不可分割的实体。例如，拉丁字母 `Ä' 在 Unicode 中可以由两个字符表示：`A' (0x41) 和组合分音符 (0x308)。 文本光标只能有效地位于这两个字符之前或之后，绝不能位于它们之间，因为那样毫无意义。在印度语系中，每个音节都构成一个字符簇。

int QTextLayout::leftCursorPosition(int oldPos) const

将光标位置恢复到oldPos 左侧、紧邻该位置处。该位置取决于字符在双向重新排序后的视觉位置。

另请参阅 rightCursorPosition() 和previousCursorPosition()。

QTextLine QTextLayout::lineAt(int i) const

返回该文本布局中第i 行的文本。

另请参阅 lineCount() 和lineForTextPosition()。

int QTextLayout::lineCount() const

返回此文本布局中的行数。

另请参阅 lineAt()。

QTextLine QTextLayout::lineForTextPosition(int pos) const

返回包含由 `pos` 指定的光标位置的那一行。

另请参阅 isValidCursorPosition() 和lineAt()。

qreal QTextLayout::maximumWidth() const

布局可扩展到的最大宽度；这基本上就是整个文本的宽度。

另请参阅 minimumWidth()。

qreal QTextLayout::minimumWidth() const

布局所需的最小宽度。这是布局中最小不可拆分子串的宽度。

另请参阅 maximumWidth()。

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

返回oldPos 之后下一个符合给定光标mode 的光标位置。如果oldPos 不是有效光标位置，则返回oldPos 的值。

另请参阅 isValidCursorPosition() 和previousCursorPosition()。

QPointF QTextLayout::position() const

布局的全球位置。该位置与边界矩形和布局过程无关。

另请参阅 setPosition()。

int QTextLayout::preeditAreaPosition() const

返回文本布局中将在编辑操作发生前被处理的区域的位置。

另请参阅 preeditAreaText()。

QString QTextLayout::preeditAreaText() const

返回在开始编辑之前插入到布局中的文本。

另请参阅 preeditAreaPosition()。

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

返回在oldPos 之前、且符合给定游标mode 的首个有效游标位置。如果oldPos 不是有效的游标位置，则返回oldPos 的值。

另请参阅 isValidCursorPosition() 和nextCursorPosition()。

int QTextLayout::rightCursorPosition(int oldPos) const

将光标位置返回至oldPos 的右侧，紧邻该位置。该位置取决于字符在双向重新排序后的视觉位置。

另请参阅 leftCursorPosition() 和nextCursorPosition()。

void QTextLayout::setCacheEnabled(bool enable)

如果enable 为true，则启用完整版面信息的缓存；否则禁用版面缓存。通常，在调用endLayout()之后，QTextLayout 会丢弃大部分版面信息，以减少内存消耗。但如果你希望随后直接绘制已排版的文本，启用缓存可能会显著加快绘制速度。

另请参阅 cacheEnabled()。

void QTextLayout::setCursorMoveStyle(Qt::CursorMoveStyle style)

将视觉光标移动样式设置为指定的style 。如果QTextLayout 由文档支持，则可以忽略此选项，转而使用QTextDocument 中的选项；该选项适用于QLineEdit 或不带QTextDocument 的自定义控件。默认值为Qt::LogicalMoveStyle 。

另请参阅 cursorMoveStyle()。

void QTextLayout::setFont(const QFont &font)

将布局的字体设置为指定的font 。布局将失效，必须重新进行布局。

另请参阅 font()。

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

将文本布局支持的附加格式设置为formats 。这些格式将在预编辑区域的文本保持原位的情况下应用。

另请参阅 formats() 和clearFormats()。

void QTextLayout::setPosition(const QPointF &p)

将文本布局移动到坐标p 。

另请参阅 position()。

void QTextLayout::setPreeditArea(int position, const QString &text)

设置布局中该区域的position 和text ，该区域将在编辑操作发生前被处理。布局将失效，必须重新进行布局。

另请参阅 preeditAreaPosition() 和preeditAreaText()。

void QTextLayout::setText(const QString &string)

将布局的文本设置为给定的string 。布局将被无效化，必须重新进行布局。

请注意，当将此QTextLayout 作为QTextDocument 的一部分使用时，此方法将不起作用。

另请参阅 text()。

void QTextLayout::setTextOption(const QTextOption &option)

将控制排版过程的文本选项结构设置为给定的option 。

另请参阅 textOption()。

QString QTextLayout::text() const

返回布局中的文本。

另请参阅 ` setText()`。

const QTextOption &QTextLayout::textOption() const

返回当前用于控制布局过程的文本选项。

另请参阅 setTextOption()。