PySide6.QtGui.QStaticText

class QStaticText

QStaticText 类在文本及其布局很少更新的情况下，能够优化文本的绘制。更多…

概要

方法

注意

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

详细描述

QStaticText 提供了一种缓存文本块布局数据的方法，以便比使用 drawText() 更高效地绘制文本，因为在每次调用 drawText() 时都会重新计算布局信息。

该类主要针对文本、字体和画家的转换在多个绘制事件中保持静态的情况提供优化。如果每次迭代都更改文本或其布局，drawText() 是更高效的选择，因为静态文本的布局将不得不重新计算以考虑新状态。

翻译画家的操作不会导致文本布局的重新计算，但会对drawStaticText()产生非常小的性能影响。更改画家的变换或画家的字体的任何其他部分将导致静态文本的布局重新计算。应尽可能避免这种情况，以最大化使用QStaticText的性能优势。

此外，drawStaticText() 仅支持仿射变换。在投影的 painter 上调用 drawStaticText() 的性能会比使用常规的 drawText() 调用稍差，因此应避免这样做。

class MyWidget: public QWidget
{
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent), m_staticText("This is static text")

protected:
    void paintEvent(QPaintEvent *)
    {
        QPainter painter(this);
        painter.drawStaticText(0, 0, m_staticText);
    }

private:
    QStaticText m_staticText;
};

QStaticText 类可用于模拟 drawText() 在无边界情况下到特定点的行为，以及当 drawText() 被调用时带有边界矩形的情况。

如果不需要边界矩形，可以创建一个QStaticText对象而不设置首选文本宽度。这样文本将占据单行。

如果你在QStaticText对象上设置了文本宽度，这将限制文本。文本将被格式化，以便没有一行超过给定的宽度。为QStaticText设置的文本宽度不会自动用于裁剪。要实现换行和裁剪，请使用setClipRect()。文本的位置由传递给drawStaticText()的参数决定，并且可以在每次调用时更改，对性能的影响最小。

为了额外的便利，可以使用QTextDocument支持的HTML子集对文本应用格式化。QStaticText将尝试使用mightBeRichText()猜测输入文本的格式，如果此函数返回true，则将其解释为富文本。要强制QStaticText将其内容显示为纯文本或富文本，请使用函数setTextFormat()并分别传入Qt::PlainText和Qt::RichText。

QStaticText 只能表示文本，因此只有改变文本布局或外观的HTML标签才会被尊重。例如，在输入的HTML中添加图像会导致图像作为布局的一部分被包含，影响文本字形的位置，但它不会被显示。结果将是输出中图像大小的空白区域。同样，使用表格会导致文本以表格格式布局，但边框不会被绘制。

如果是第一次绘制静态文本，或者自上次绘制以来静态文本或画家的字体已被更改，则必须重新计算文本的布局。在某些绘制引擎上，更改画家的矩阵也会导致布局重新计算。特别是，除了OpenGL2绘制引擎之外的任何引擎都会发生这种情况。重新计算布局将在发生drawStaticText()调用时增加开销。为了避免在绘制事件中出现这种开销，您可以提前调用prepare()以确保布局已计算。

class PerformanceHint

此枚举了可以在QStaticText上设置的不同性能提示。这些提示可用于指示QStaticText应尽可能使用额外的缓存，以提高性能，但会牺牲内存。特别是，在QStaticText上设置性能提示AggressiveCaching将在使用OpenGL图形系统或绘制到QOpenGLWidget时提高性能。

常量

描述

QStaticText.ModerateCaching

以低内存成本进行基本缓存以实现高性能。

QStaticText.AggressiveCaching

在可用时使用额外的缓存。这可能会以更高的内存成本提高性能。
__init__()

构造一个空的 QStaticText

__init__(other)
Parameters:

其他 – QStaticText

构造一个QStaticText对象，它是other的副本。

__init__(text)
Parameters:

文本 – str

使用给定的text构造一个QStaticText对象。

__ne__(other)
Parameters:

其他 – QStaticText

Return type:

布尔

将other与此QStaticText进行比较。如果文本、字体或最大大小不同，则返回true。

__eq__(other)
Parameters:

其他 – QStaticText

Return type:

布尔

将other与此QStaticText进行比较。如果文本、字体和文本宽度相等，则返回true。

performanceHint()
Return type:

PerformanceHint

返回为QStaticText设置的性能提示。

另请参阅

setPerformanceHint()

prepare([matrix=QTransform()[, font=QFont()]])
Parameters:

准备QStaticText对象，以便在调用实际的drawStaticText()时使用给定的matrix和font进行绘制，以避免开销。

当调用drawStaticText()时，如果自上次绘制以来QStaticText对象的任何部分发生了变化，QStaticText的布局将被重新计算。如果画家的字体与上次绘制QStaticText时不同，或者在任何其他绘图引擎（非OpenGL2引擎）上，如果自上次绘制静态文本以来画家的矩阵已被更改，布局也将被重新计算。

为了避免在更改后第一次绘制QStaticText时创建布局的开销，您可以使用prepare()函数并传入绘制文本时预期使用的matrix和font。

setPerformanceHint(performanceHint)
Parameters:

performanceHint – PerformanceHint

根据提供的performanceHint设置QStaticText的性能提示。performanceHint用于自定义内部缓存量以提高性能。

默认是ModerateCaching。

注意

此函数将导致文本布局需要重新计算。

另请参阅

performanceHint()

setText(text)
Parameters:

文本 – str

将QStaticText的文本设置为text。

注意

此函数将导致文本布局需要重新计算。

另请参阅

text()

setTextFormat(textFormat)
Parameters:

textFormat – TextFormat

设置QStaticText的文本格式为textFormat。如果textFormat设置为Qt::AutoText（默认值），文本的格式将尝试使用函数mightBeRichText()来确定。如果文本格式是Qt::PlainText，则文本将按原样显示，而如果格式是Qt::RichText，则文本将被解释为HTML。QStaticText支持改变文本字体、颜色或布局的HTML标签。

注意

此函数将导致文本布局需要重新计算。

另请参阅

textFormat() setText() text()

setTextOption(textOption)
Parameters:

textOption – QTextOption

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

另请参阅

textOption()

setTextWidth(textWidth)
Parameters:

textWidth – 浮点数

设置此QStaticText的首选宽度。如果文本比指定的宽度宽，它将被分成多行并垂直增长。如果文本不能被分成多行，它将比指定的textWidth大。

将首选文本宽度设置为负数将导致文本无边界。

使用 size() 获取文本的实际大小。

注意

此函数将导致文本布局需要重新计算。

另请参阅

textWidth() size()

size()
Return type:

QSizeF

返回此QStaticText的边界矩形的大小。

另请参阅

textWidth()

swap(other)
Parameters:

其他 – QStaticText

将此静态文本实例与 other 交换。此函数非常快且永远不会失败。

text()
Return type:

字符串

返回 QStaticText 的文本。

另请参阅

setText()

textFormat()
Return type:

TextFormat

返回 QStaticText 的文本格式。

textOption()
Return type:

QTextOption

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

另请参阅

setTextOption()

textWidth()
Return type:

浮点数

返回此QStaticText的首选宽度。

另请参阅

setTextWidth()