class QTextLayout#

类 QTextLayout 用于布局和渲染文本。更多信息...

概述#

方法#

注意

此文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译存在问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE创建工单来告知我们。

详细描述#

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

它提供了现代文本布局引擎所期望的许多功能，包括Unicode兼容的渲染、换行和处理光标定位。它还可以生成和渲染与设备无关的布局，这对于所见即所得应用程序非常重要。

该类有一个相对较低级别的API，除非您打算为某些专用小部件实现自己的文本渲染，否则您可能不需要直接使用它。

QTextLayout 可以与纯文本和富文本一起使用。

QTextLayout 可以用来创建指定宽度的 QTextLine 实例序列，并将它们独立地放置在屏幕上。一旦完成布局，这些行就可以在绘图设备上绘制。

要布局的文本可以通过构造函数提供，也可以通过 setText() 设置。

布局可以视为 QTextLine 对象的序列；使用 createLine() 创建 QTextLine 实例，并使用 lineAt() 或 lineForTextPosition() 检索创建的行。

以下是一个展示布局阶段的代码片段

leading = fontMetrics.leading()
height = 0
textLayout.setCacheEnabled(True)
textLayout.beginLayout()
while True:
    line = textLayout.createLine()
    if not line.isValid():
        break
    line.setLineWidth(lineWidth)
    height += leading
    line.setPosition(QPointF(0, height))
    height += line.height()

textLayout.endLayout()

然后可以通过调用布局的 draw() 函数来将文本渲染出来

painter = QPainter(self)
textLayout.draw(painter, QPoint(0, 0))

也可以单独绘制每一行，例如，绘制刚好适应小部件的最后一行并使用省略号表示

painter = QPainter(self)
fontMetrics = painter.fontMetrics()
lineSpacing = fontMetrics.lineSpacing()
y = 0
textLayout = QTextLayout(content, painter.font())
textLayout.beginLayout()
while True:
    line = textLayout.createLine()
    if not line.isValid():
        break
    line.setLineWidth(width())
    nextLineY = y + lineSpacing
    if height() >= nextLineY + lineSpacing:
        line.draw(painter, QPoint(0, y))
        y = nextLineY
    else:
        lastLine = content.mid(line.textStart())
        elidedLastLine = fontMetrics.elidedText(lastLine, Qt.ElideRight, width())
        painter.drawText(QPoint(0, y + fontMetrics.ascent()), elidedLastLine)
        line = textLayout.createLine()
        break


textLayout.endLayout()

对于文本中的某个位置，可以使用 isValidCursorPosition() 、nextCursorPosition() 和 previousCursorPosition() 查找有效的光标位置。

《QTextLayout》自身可以使用setPosition()进行定位；它有一个boundingRect() （边界矩形），以及minimumWidth()和maximumWidth()（最小宽度和最大宽度）。

参阅

QStaticText

class GlyphRunRetrievalFlag#

(继承自enum.Flag类) GlyphRunRetrievalFlag指定传给glyphRuns()函数的标志，以确定在QGlyphRun对象中返回布局的哪些属性。由于每个属性都会消耗内存，可能需要额外的分配，因此只请求您稍后需要访问的属性是一种很好的做法。

常量

描述

QTextLayout.RetrieveGlyphIndexes

检索字体中与符号对应的索引。

QTextLayout.RetrieveGlyphPositions

检索布局中符号的相对位置。

QTextLayout.RetrieveStringIndexes

检索对应于每个符号的原始字符串中的索引。

QTextLayout.RetrieveString

从布局中检索原始源字符串。

QTextLayout.RetrieveAll

检索布局的所有可用属性。

参阅

glyphRuns() glyphRuns()

新增于版本 6.5。

class CursorMode#

常量

描述

QTextLayout.SkipCharacters

QTextLayout.SkipWords
__init__(text)#
参数：

text – 字符串

构造用于布局给定text的文本布局。

__init__()

构造一个空的文本布局。

参阅

setText()

__init__()
参数：

b – QTextBlock

构造用于布局给定text的文本布局。

__init__(text, font[, paintdevice=None])
参数：

使用指定的font构造文本布局过程以显示给定的 text。

所有指标和布局计算都将基于绘图设备，paintdevice 进行。如果 paintdevice 为 None，计算将基于屏幕指标进行。

beginLayout()#

开始布局过程。

警告

这将使布局失效，因此现在应丢弃所有引用先前内容的现有 QTextLine 对象。

参阅

endLayout()

boundingRect()#
返回类型:

QRectF

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

cacheEnabled()#
返回类型:

bool

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

clearFormats()#

清除文本布局支持的所有附加格式的列表。

clearLayout()#

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

警告

这将使布局失效，因此现在应丢弃所有引用先前内容的现有 QTextLine 对象。

createLine()#
返回类型:

QTextLine

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

文本布局创建一个新行对象，该对象从布局中的最后一行之后开始，或者在布局为空时从开始处。布局维护一个内部光标，并且在调用 setLineWidth() 函数时，每个行从光标位置开始填充文本。

调用 setLineWidth() 后，可以创建一个新的行并填充文本。重复此过程会在 QTextLayout 中排列整个文本块。如果没有文本要插入布局中，返回的 QTextLine 将不会是有效的（isValid() 将返回 false）。

cursorMoveStyle()#
返回类型:

CursorMoveStyle

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

draw(p, pos[, selections=list()[, clip=QRectF()]])#
参数：

在由 pos 指定的位置上，将整个布局绘制在 p 绘图器上。绘制的布局包括给定的 selections，并在由 clip 指定的矩形内剪切。

drawCursor(p, pos, cursorPosition, width)#
参数：

使用指定的 painter 和 width 在给定的 position 上绘制文本光标。文本中的相应位置由 cursorPosition 指定。

drawCursor(p, pos, cursorPosition)
参数：

这是一个重载函数。

使用指定的 painter 在给定的 position 位置处绘制文本光标，并指定文本中的对应位置为 cursorPosition。

endLayout()#

结束布局过程。

参阅

beginLayout()

font()#
返回类型:

QFont

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

参阅

setFont()

formats()#
返回类型:

返回 QTextLayout.FormatRange 的列表

返回文本布局支持的所有额外格式的列表。

glyphRuns([from=-1[, length=-1]])#
参数：

  • from – int

  • length – int

返回类型:

返回包含 QGlyphRun 的列表

这是一个重载函数。

返回在此次 QTextLayout 中从位置 from 开始，长度为 length 的所有字符对应的字形索引和位置。这是一个昂贵的函数，不应在时间敏感的上下文中调用。

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

注意

这相当于调用 glyphRuns (from, length, QTextLayout::GlyphRunRetrievalFlag::GlyphIndexes | QTextLayout::GlyphRunRetrievalFlag::GlyphPositions)。

参阅

draw() drawGlyphRun()

glyphRuns(from, length, flags)
参数：

  • from – int

  • length – int

  • flags – GlyphRunRetrievalFlag 的组合

返回类型:

返回包含 QGlyphRun 的列表

这是一个重载函数。

返回在此次 QTextLayout 中从位置 from 开始，长度为 length 的所有字符对应的字形索引和位置。这是一个昂贵的函数，不应在时间敏感的上下文中调用。

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

retrievalFlags 指定要从布局中检索 QGlyphRun 的哪些属性。为了最小化分配和内存消耗，应该只包含您稍后需要访问的属性。

isValidCursorPosition(pos)#
参数：

pos – int

返回类型:

bool

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

在 Unicode 上下文中，文本中某些位置不是有效的光标位置，因为这些位置在 Unicode 代理或图形簇中。

图形簇是由两个或更多 Unicode 字符组成的序列，这些字符在屏幕上形成一个不可分割的实体。例如，拉丁字符 `Ä’ 可以由两个字符表示，`A‘ (0x41) 和组合变音符号 (0x308)。文本光标只能合法地位于这两个字符之前或之后，而不能位于其间，因为这没有意义。在印度语系中，每个音节都是一个图形簇。

leftCursorPosition(oldPos)#
参数：

oldPos – int

返回类型:

int

返回 oldPos 左侧的光标位置，紧挨着它。这是根据字符的视觉位置，在双向重新排序后。

lineAt(i)#
参数：

i – int

返回类型:

QTextLine

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

lineCount()#
返回类型:

int

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

参阅

lineAt()

lineForTextPosition(pos)#
参数：

pos – int

返回类型:

QTextLine

返回由 pos 指定的光标位置所在的行。

maximumWidth()#
返回类型:

float

布局可以扩展到的最大宽度；这实际上是整篇文本的宽度。

警告

此函数仅在布局完成后返回有效值。

参阅

minimumWidth()

minimumWidth()#
返回类型:

float

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

警告

此函数仅在布局完成后返回有效值。

参阅

maximumWidth()

nextCursorPosition(oldPos[, mode=QTextLayout.CursorMode.SkipCharacters])#
参数：
返回类型:

int

返回老位置`oldPos`之后的下一个有效光标位置，该位置遵循给定的光标模式。如果`oldPos`不是有效光标位置，则返回`oldPos`的值。

position()#
返回类型:

QPointF

布局的全局位置。这独立于边界矩形和布局过程。

参阅

setPosition()

preeditAreaPosition()#
返回类型:

int

返回文本布局中编辑前要处理区域的当前位置。

preeditAreaText()#
返回类型:

str

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

previousCursorPosition(oldPos[, mode=QTextLayout.CursorMode.SkipCharacters])#
参数：
返回类型:

int

返回老位置`oldPos`之前的第一个有效光标位置，该位置遵循给定的光标模式。如果`oldPos`不是有效光标位置，则返回`oldPos`的值。

rightCursorPosition(oldPos)#
参数：

oldPos – int

返回类型:

int

返回紧挨着`oldPos`右侧的光标位置，依赖于字符的视觉位置，双向重排后。

setCacheEnabled(enable)#
参数：

enable – bool

如果 enable 为真，则启用完整布局信息的缓存；否则禁用布局缓存。通常 QTextLayout 在调用 endLayout() 之后抛弃大部分布局信息以减少内存消耗。如果您需要紧接着绘制布局后的文本，启用缓存可以显著加快绘制速度。

setCursorMoveStyle(style)#
参数：

style – CursorMoveStyle

将可视化光标移动样式设置为给定的 style。如果 QTextLayout 由文档支持，您可以忽略此选项并使用 QTextDocument 中的选项，此选项用于类似 QLineEdit 或没有 QTextDocument 的自定义小部件。默认值为 Qt::LogicalMoveStyle。

setFlags(flags)#
参数：

flags – int

setFont(f)#
参数：

f – QFont

将布局的字体设置为给定的 font。布局将无效化并必须重新布局。

参阅

font()

setFormats(overrides)#
参数：

overrides – .list of QTextLayout.FormatRange

将文本布局支持的超集格式设置为 formats。这些格式会应用于插入区域中的文本。

setPosition(p)#
参数：

p – QPointF

将文本布局移动到点 p。

参阅

position()

setPreeditArea(position, text)#
参数：

  • position – int

  • text – 字符串

设置在编辑发生前处理的布局区域的 position 和 text。布局无效化，必须重新布局。

setRawFont(rawFont)#
参数：

rawFont – QRawFont

setText(string)#
参数：

string – str

将布局的文本设置为给定的 string。布局将无效，必须再次布局。

注意，当将此 QTextLayout 作为 QTextDocument 的一部分使用时，此方法将无效果。

参阅

text()

setTextOption(option)#
参数：

option – QTextOption

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

参阅

textOption()

text()#
返回类型:

str

返回布局的文本。

参阅

setText()

textOption()#
返回类型:

QTextOption

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