PySide6.QtGui.QTextLayout¶

class QTextLayout¶

QTextLayout 类用于布局和渲染文本。More_…

概要¶

方法¶

def __init__()
def beginLayout()
def boundingRect()
def cacheEnabled()
def clearFormats()
def clearLayout()
def createLine()
def cursorMoveStyle()
def draw()
def drawCursor()
def endLayout()
def font()
def formats()
def glyphRuns()
def isValidCursorPosition()
def leftCursorPosition()
def lineAt()
def lineCount()
def lineForTextPosition()
def maximumWidth()
def minimumWidth()
def nextCursorPosition()
def position()
def preeditAreaPosition()
def preeditAreaText()
def previousCursorPosition()
def rightCursorPosition()
def setCacheEnabled()
def setCursorMoveStyle()
def setFlags()
def setFont()
def setFormats()
def setPosition()
def setPreeditArea()
def setRawFont()
def setText()
def setTextOption()
def text()
def textOption()

注意

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

详细描述¶

警告

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

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

该类具有相当低级别的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()

常量	描述
QTextLayout.RetrieveGlyphIndexes	检索字体中与字形对应的索引。
QTextLayout.RetrieveGlyphPositions	检索布局中字形的相对位置。
QTextLayout.RetrieveStringIndexes	检索原始字符串中与每个字形对应的索引。
QTextLayout.RetrieveString	从布局中检索原始源字符串。
QTextLayout.RetrieveAll	检索布局的所有可用属性。

在6.5版本中添加。

class CursorMode¶

常量	描述
QTextLayout.SkipCharacters
QTextLayout.SkipWords

__init__()¶

构建一个空的文本布局。

另请参阅

setText()

__init__(text)

Parameters:: 文本 – str

构建一个文本布局来布局给定的text。

__init__(b)

Parameters:: b – QTextBlock

构建一个文本布局来布局给定的 text。

__init__(text, font[, paintdevice=None])

Parameters:

文本 – str
字体 – QFont
paintdevice – QPaintDevice

构建一个文本布局，以使用指定的font来布局给定的text。

所有的度量和布局计算都将根据绘制设备 paintdevice 进行。如果 paintdevice 是 None，则计算将使用屏幕度量进行。

beginLayout()¶

开始布局过程。

警告

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

另请参阅

endLayout()

boundingRect()¶

Return type:: QRectF

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

cacheEnabled()¶

Return type:: 布尔

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

另请参阅

setCacheEnabled()

clearFormats()¶

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

另请参阅

formats() setFormats()

clearLayout()¶

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

警告

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

createLine()¶

Return type:: QTextLine

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

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

一旦调用setLineWidth()，就可以创建一条新行并填充文本。重复此过程将布局包含在QTextLayout中的整个文本块。如果没有剩余的文本可以插入到布局中，返回的QTextLine将无效（isValid()将返回false）。

cursorMoveStyle()¶

Return type:: CursorMoveStyle

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

另请参阅

setCursorMoveStyle()

draw(p, pos[, selections=list()[, clip=QRectF()]])¶

Parameters:

p – QPainter
pos – QPointF
selections – QTextLayout.FormatRange 的列表
clip – QRectF

在画师 p 上绘制整个布局，位置由 pos 指定。渲染的布局包括给定的 selections，并在 clip 指定的矩形内进行裁剪。

drawCursor(p, pos, cursorPosition)¶

Parameters:

p – QPainter
pos – QPointF
cursorPosition – int

这是一个重载函数。

使用指定的painter在给定的position处绘制一个文本光标。文本中的对应位置由cursorPosition指定。

drawCursor(p, pos, cursorPosition, width)

Parameters:

p – QPainter
pos – QPointF
cursorPosition – int
width – int

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

endLayout()¶

结束布局过程。

另请参阅

beginLayout()

font()¶

Return type:: QFont

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

另请参阅

setFont()

formats()¶

Return type:: QTextLayout.FormatRange的列表

返回文本布局支持的附加格式列表。

另请参阅

setFormats() clearFormats()

glyphRuns([from=-1[, length=-1]])¶

Parameters:

from – 整数
length – int

Return type:

QGlyphRun的列表

这是一个重载函数。

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

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

注意

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

另请参阅

draw() drawGlyphRun()

glyphRuns(from, length, flags)

Parameters:

from – 整数
length – int
flags – GlyphRunRetrievalFlag 的组合

Return type:

QGlyphRun的列表

这是一个重载函数。

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

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

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

另请参阅

draw() drawGlyphRun()

isValidCursorPosition(pos)¶

Parameters:: pos – 整数
Return type:: 布尔

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

在Unicode上下文中，文本中的某些位置不是有效的光标位置，因为这些位置位于Unicode代理项或字素簇内部。

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

leftCursorPosition(oldPos)¶

Parameters:: oldPos – int
Return type:: 整数

将光标位置返回到oldPos的左侧，紧邻它。它依赖于字符的视觉位置，经过双向重新排序后。

另请参阅

rightCursorPosition() previousCursorPosition()

lineAt(i)¶

Parameters:: i – 整数
Return type:: QTextLine

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

另请参阅

lineCount() lineForTextPosition()

lineCount()¶

Return type:: 整数

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

另请参阅

lineAt()

lineForTextPosition(pos)¶

Parameters:: pos – 整数
Return type:: QTextLine

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

另请参阅

isValidCursorPosition() lineAt()

maximumWidth()¶

Return type:: 浮点数

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

警告

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

另请参阅

minimumWidth()

minimumWidth()¶

Return type:: 浮点数

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

警告

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

另请参阅

maximumWidth()

nextCursorPosition(oldPos[, mode=QTextLayout.CursorMode.SkipCharacters])¶

Parameters:

oldPos – int
mode – CursorMode

Return type:

整数

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

另请参阅

isValidCursorPosition() previousCursorPosition()

position()¶

Return type:: QPointF

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

另请参阅

setPosition()

preeditAreaPosition()¶

Return type:: 整数

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

另请参阅

preeditAreaText()

preeditAreaText()¶

Return type:: 字符串

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

另请参阅

preeditAreaPosition()

previousCursorPosition(oldPos[, mode=QTextLayout.CursorMode.SkipCharacters])¶

Parameters:

oldPos – int
mode – CursorMode

Return type:

整数

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

另请参阅

isValidCursorPosition() nextCursorPosition()

rightCursorPosition(oldPos)¶

Parameters:: oldPos – int
Return type:: 整数

将光标位置返回到oldPos的右侧，紧邻它。它依赖于字符的视觉位置，经过双向重新排序后。

另请参阅

leftCursorPosition() nextCursorPosition()

setCacheEnabled(enable)¶

Parameters:: enable – 布尔值

如果enable为true，则启用完整布局信息的缓存；否则禁用布局缓存。通常QTextLayout在调用endLayout()后会丢弃大部分布局信息以减少内存消耗。然而，如果您想在布局后直接绘制文本，启用缓存可能会显著加快绘制速度。

另请参阅

cacheEnabled()

setCursorMoveStyle(style)¶

Parameters:: style – CursorMoveStyle

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

另请参阅

cursorMoveStyle()

setFlags(flags)¶

Parameters:: flags – 整数

setFont(f)¶

Parameters:: f – QFont

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

另请参阅

font()

setFormats(overrides)¶

Parameters:: overrides – .QTextLayout.FormatRange 的列表

设置文本布局支持的附加格式为formats。这些格式将应用于预编辑区域的文本。

另请参阅

formats() clearFormats()

setPosition(p)¶

Parameters:: p – QPointF

将文本布局移动到点 p。

另请参阅

position()

setPreeditArea(position, text)¶

Parameters:

position – int
文本 – str

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

另请参阅

preeditAreaPosition() preeditAreaText()

setRawFont(rawFont)¶

Parameters:: rawFont – QRawFont

setText(string)¶

Parameters:: 字符串 – str

将布局的文本设置为给定的string。布局将失效，必须重新布局。

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

另请参阅

text()

setTextOption(option)¶

Parameters:: 选项 – QTextOption

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

另请参阅

textOption()

text()¶

Return type:: 字符串

返回布局的文本。

另请参阅

setText()

textOption()¶

Return type:: QTextOption

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

另请参阅

setTextOption()

class FormatRange¶

概要¶

方法¶

def __ne__()
def __eq__()

注意

详细描述¶

PySide6.QtGui.QTextLayout.FormatRange.start¶

PySide6.QtGui.QTextLayout.FormatRange.length¶

PySide6.QtGui.QTextLayout.FormatRange.format¶

__ne__(rhs)¶

Parameters:: rhs – FormatRange
Return type:: 布尔

如果lhs和rhs中的start、length或format字段中的任何一个包含不同的值，则返回true。

__eq__(rhs)¶

Parameters:: rhs – FormatRange
Return type:: 布尔

如果lhs和rhs中的start、length和format字段分别包含相同的值，则返回true。