pyglet.text.layout
高效地呈现简单文本和格式化文档。
提供了三个布局类：
TextLayout整个文档是在呈现之前进行布局的。该布局将与同一批中的其他布局分组(允许高效地呈现多个布局)。
对布局或文档的任何更改，甚至查询某些属性，都会导致重新布局整个文档。
ScrollableTextLayout基于
TextLayout()。单独的组用于布局，它将布局的内容裁剪到布局矩形。此外，布局的内容可以在该矩形内使用
view_x和view_y属性。IncrementalTextLayout基于
ScrollableTextLayout。修改布局或文档时，仅重新布局受影响的区域。这允许对文本进行高效的交互编辑和样式设置。
实际只渲染布局的可见部分；当滚动视区时，会根据需要渲染和丢弃其他部分。这允许高效地查看和编辑大型文档。
此外，此类还提供了用于定位插入符号在文档中的位置以及用于显示交互式文本选择的方法。
这三个布局类都可以与以下任一类一起使用 UnformattedDocument 或 FormattedDocument ，并且可以是单行或 multiline 。这些选项的组合有效地提供了12种不同的文本显示可能性。
样式属性
布局类可以识别以下字符样式属性名称。数据类型和单位是指定的。
如果属性被标记为“as a Distance”，则假定该值以像素为单位(如果以整型或浮点型给出)，否则为以下形式的字符串 "0u" 是必需的，其中 0 是距离和 u 是单位；其中之一 "px" (像素)， "pt" (积分)， "pc" (Picas)， "cm" (厘米)， "mm" (毫米)或 "in" (英寸)。例如, "14pt" 是覆盖14个点的距离，在默认DPI为96时为18个像素。
font_name字体系列名称，指定给
pyglet.font.load()。font_size字体大小，以磅为单位。
bold布尔型。
italic布尔型。
underline范围(0,255)中的整数数组，提供RGBA下划线颜色，或无(默认)，表示不带下划线。
kerning要在字形之间插入的附加空格，如距离。默认为0。
baseline字形基线与直线基线的偏移量，如距离。正值表示上标，负值表示下标。默认为0。
color范围(0,255)中的四元组整数，提供RGBA文本颜色
background_color范围(0,255)中的四元组整数，提供RGBA文本背景颜色；或
None用于无背景填充。
可识别以下段落样式属性名称。请注意，文档对段落样式的处理与对字符样式的处理没有什么不同：应用程序负责在整个段落上设置样式，否则结果不确定。
alignleft(默认)，center或right。indent要在段落第一行的第一个字形之前插入的附加水平空格，如距离。
leading在段落内的连续行之间插入的附加空格，如距离。默认为0。
line_spacing距离段落中连续基线之间的距离，如距离默认为
None，它会根据字体的升降自动计算每行的最紧行距。margin_left左段边距，如距离。
margin_right右段页边距，如距离。
margin_top段落上方的页边距，如距离。
margin_bottom段落下方的页边距，如距离。相邻页边距不会折叠。
tab_stops从文本布局的左边缘测量的水平制表位列表，以距离表示。默认为空列表。当制表位用完时，它们隐式地以50像素的间隔继续。
wrapchar，word、True(默认)或False。为防止文本溢出而对文本进行换行的边界。使用char，该行在文本中的任意位置换行；使用word或为True，则该行在单词之间的适当边界处换行；如果为False，则该行不会换行，并且可能会溢出布局宽度。
其他属性可用于在文档中存储其他样式信息；内置文本类将忽略这些属性。
- class IncrementalTextDecorationGroup
- class IncrementalTextLayout
适合交互编辑和/或滚动大型文档的显示文本。
不像
TextLayout()和ScrollableTextLayout时，此类仅为可见的文本行生成顶点列表。滚动文档时，会根据需要删除和创建顶点列表，以将视频内存使用量保持在最低水平并提高渲染速度。对文档的更改会迅速反映在此版面中，因为只有受影响的行(S)会被重排。使用
begin_update()和end_update()以进一步减少所需的处理量。布局还可以显示文本选择(具有不同背景颜色的文本)。这个
Caret类实现可见的文本光标，并提供用于滚动、选择和编辑增量文本布局中的文本的事件处理程序。- 类变量:
group_class (ClassVar[type[IncrementalTextLayoutGroup]]) -- Default group used to set the state for all glyphs.
decoration_class (ClassVar[type[IncrementalTextDecorationGroup]]) -- Default group used to set the state for all decorations including background colors and underlines.
- __init__(
- document: AbstractDocument,
- width: int,
- height: int,
- x: float = 0,
- y: float = 0,
- z: float = 0,
- anchor_x: Literal['left', 'center', 'right'] = 'left',
- anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'bottom',
- rotation: float = 0,
- multiline: bool = False,
- dpi: int | None = None,
- batch: Batch | None = None,
- group: Group | None = None,
- program: ShaderProgram | None = None,
- wrap_lines: bool = True,
初始化文本布局。
- 参数:
document (
AbstractDocument) -- 要显示的文档。x (
float) -- 标签的X坐标。y (
float) -- 标签的Y坐标。z (
float) -- 标签的Z坐标。width (
int) -- 布局宽度（以像素为单位），或无height (
int) -- 布局高度（以像素为单位），或无anchor_x (
Literal['left','center','right']) -- X坐标的锚点。anchor_y (
Literal['top','bottom','center','baseline']) -- Y坐标的锚点。rotation (
float) -- 以度数为单位旋转标签的量。正值将是顺时针旋转，负值将导致逆时针旋转。multiline (
bool) -- 如果为False，则忽略新元素和段落字符，并且文本不会进行单词包装。如果为True，则仅在 wrap_lines 是真的。group (
Group|None) -- 可选组，用于此文本布局使用的所有内部组的父级。 请注意，具有相同组的布局将在批处理中同时渲染。program (
ShaderProgram|None) -- 可选使用的图形着色器。将影响布局中的所有字形。wrap_lines (
bool) -- 如果为真且 multiline 为True，则文本将使用指定的宽度进行单词包装。init_document -- 如果为True，文档将被初始化。如果要进行子分类，那么您可能希望通过更改为False来避免重复初始化。
- get_point_from_position( ) tuple[float, float]
获取文档中字符位置的X、Y坐标。
结束一条线的位置有一个模糊点：它可以是这条线的终点，也可以是下一条线的起点。您可以选择指定行索引来消除大小写的歧义。
生成的Y坐标提供了直线的基线。
- on_delete_text(start: int, end: int) None
的事件处理程序 AbstractDocument.on_delete_text 。
事件处理程序由文本布局绑定；应用程序不需要与此方法交互。
- 返回类型:
- on_insert_text(start: int, text: str) None
的事件处理程序 AbstractDocument.on_insert_text 。
事件处理程序由文本布局绑定；应用程序不需要与此方法交互。
- 返回类型:
- on_layout_update() None
部分或全部布局文本已重排。
文本回流是由文档编辑或版面大小更改引起的。对版面位置或活动选定内容的更改以及某些文档编辑(如文本颜色)不会导致重排。
处理此事件可更新图形元素的位置，该位置取决于字形或线条的布局位置。
- 活动:
- 返回类型:
- property anchor_x: Literal['left', 'center', 'right']
水平锚点对齐。
此属性确定
x协调。支持以下值：
"left"(违约)X坐标给出布局左边缘的位置。
"center"X坐标给出了布局中心的位置。
"right"X坐标给出布局的右边缘的位置。
为了计算由该路线产生的位置，布局的宽度被视为
width如果multiline是真的并且wrap_lines为True，否则为content_width。
- property anchor_y: Literal['top', 'bottom', 'center', 'baseline']
垂直锚点对齐。
此属性确定
y协调。支持以下值：
"top"Y坐标给出布局顶边的位置。
"center"Y坐标给出了布局中心的位置。
"baseline"Y坐标提供布局中第一行文本的基线位置。
"bottom"(违约)Y坐标提供布局的底边的位置。
为了计算由该路线产生的位置，布局的高度被视为以下最小的
height和content_height。另请参阅
content_valign。
- event_types: list = ['on_layout_update', 'on_translation_update']
- property height: int
定义的布局最大高度（以像素为单位），或无。
什么时候 height 不是None，则它会影响文本的位置
anchor_y和content_valign都被使用过。
- lines: list[_Line]
- property multiline: bool
设置是否启用多行布局。
如果
multiline为False，则忽略白线和段落字符，并且文本不进行单词包装。如果为True，则文本仅在wrap_lines是真的。
- property rotation: float
旋转将始终为0，因为增量布局无法旋转。
- 抛出:
NotImplementedError -- 不支持旋转增量文本布局。
- property selection_background_color: tuple[int, int, int, int]
活动选定内容的背景色。
该颜色是一个RGBA元组，其组件在范围内 [0, 255] 。
- property selection_end: int
活动选定内容的结束位置(独占)。
- 看见:
py：meth：'~pyglet.text.layout.IncrementalTextlayout.set_selection '
- property selection_start: int
活动选定内容的开始位置。
- 看见:
py：meth：'~pyglet.text.layout.IncrementalTextlayout.set_selection '
- property view_x: int
水平滚动偏移量。
初始值为0，文本的左边缘将接触布局边界的左侧。如果为正值，文本将向右滚动。值将自动裁剪到范围内
[0, content_width - width]
- property view_y: int
垂直滚动偏移量。
初始值为0，文本的顶部将接触到布局边界的顶部(除非内容高度小于布局高度，在这种情况下 content_valign 是使用的)。
负值会导致文本向上“滚动”。范围外的值
[height - content_height, 0]会自动在范围内进行裁剪。
- class ScrollableTextDecorationGroup
创建文本装饰渲染组。
当
Label被创建;应用程序通常不需要显式创建它。
- class ScrollableTextLayout
在可滚动的视区中显示文本。
此类不显示滚动条或处理滚动事件；它只剪辑将绘制在
TextLayout()给出的布局的边界x，y，width和height；并将文本偏移滚动偏移量。使用
view_x和view_y在视口中滚动文本。- 类变量:
group_class (ClassVar[type[ScrollableTextLayoutGroup]]) -- Default group used to set the state for all glyphs.
decoration_class (ClassVar[type[ScrollableTextDecorationGroup]]) -- Default group used to set the state for all decorations including background colors and underlines.
- __init__(
- document: AbstractDocument,
- width: int,
- height: int,
- x: float = 0,
- y: float = 0,
- z: float = 0,
- anchor_x: Literal['left', 'center', 'right'] = 'left',
- anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'bottom',
- rotation: float = 0,
- multiline: bool = False,
- dpi: int | None = None,
- batch: Batch | None = None,
- group: Group | None = None,
- program: ShaderProgram | None = None,
- wrap_lines: bool = True,
初始化文本布局。
- 参数:
document (
AbstractDocument) -- 要显示的文档。x (
float) -- 标签的X坐标。y (
float) -- 标签的Y坐标。z (
float) -- 标签的Z坐标。width (
int) -- 布局宽度（以像素为单位），或无height (
int) -- 布局高度（以像素为单位），或无anchor_x (
Literal['left','center','right']) -- X坐标的锚点。anchor_y (
Literal['top','bottom','center','baseline']) -- Y坐标的锚点。rotation (
float) -- 以度数为单位旋转标签的量。正值将是顺时针旋转，负值将导致逆时针旋转。multiline (
bool) -- 如果为False，则忽略新元素和段落字符，并且文本不会进行单词包装。如果为True，则仅在 wrap_lines 是真的。group (
Group|None) -- 可选组，用于此文本布局使用的所有内部组的父级。 请注意，具有相同组的布局将在批处理中同时渲染。program (
ShaderProgram|None) -- 可选使用的图形着色器。将影响布局中的所有字形。wrap_lines (
bool) -- 如果为真且 multiline 为True，则文本将使用指定的宽度进行单词包装。init_document -- 如果为True，文档将被初始化。如果要进行子分类，那么您可能希望通过更改为False来避免重复初始化。
- property anchor_x: Literal['left', 'center', 'right']
水平锚点对齐。
此属性确定
x协调。支持以下值：
"left"(违约)X坐标给出布局左边缘的位置。
"center"X坐标给出了布局中心的位置。
"right"X坐标给出布局的右边缘的位置。
为了计算由该路线产生的位置，布局的宽度被视为
width如果multiline是真的并且wrap_lines为True，否则为content_width。
- property anchor_y: Literal['top', 'bottom', 'center', 'baseline']
垂直锚点对齐。
此属性确定
y协调。支持以下值：
"top"Y坐标给出布局顶边的位置。
"center"Y坐标给出了布局中心的位置。
"baseline"Y坐标提供布局中第一行文本的基线位置。
"bottom"(违约)Y坐标提供布局的底边的位置。
为了计算由该路线产生的位置，布局的高度被视为以下最小的
height和content_height。另请参阅
content_valign。
- property view_x: int
水平滚动偏移量。
初始值为0，文本的左边缘将接触布局边界的左侧。如果为正值，文本将向右滚动。值将自动裁剪到范围内
[0, content_width - width]
- class ScrollableTextLayoutGroup
的默认渲染组
ScrollableTextLayout。该组维护内部状态以指定查看区域和滚动。由于组具有特定于文本布局的内部状态，因此永远不会共享组。
- class TextDecorationGroup
创建文本装饰渲染组。
当
Label被创建;应用程序通常不需要显式创建它。
- class TextLayout
布局和显示文档。
此类旨在显示文档。
Label()和HTMLLabel()为此类提供一个方便的接口。某些属性可能会导致文档被重新创建而不是更新。详情请参阅物业文件。
- 类变量:
group_class (
ClassVar[type[TextLayoutGroup]]) -- Default group used to set the state for all glyphs.decoration_class (
ClassVar[type[TextDecorationGroup]]) -- Default group used to set the state for all decorations including background colors and underlines.
- __init__(
- document: AbstractDocument,
- width: int | None = None,
- height: int | None = None,
- x: float = 0,
- y: float = 0,
- z: float = 0,
- anchor_x: Literal['left', 'center', 'right'] = 'left',
- anchor_y: Literal['top', 'bottom', 'center', 'baseline'] = 'bottom',
- rotation: float = 0,
- multiline: bool = False,
- dpi: int | None = None,
- batch: Batch | None = None,
- group: Group | None = None,
- program: ShaderProgram | None = None,
- wrap_lines: bool = True,
- init_document: bool = True,
初始化文本布局。
- 参数:
document (
AbstractDocument) -- 要显示的文档。x (
float) -- 标签的X坐标。y (
float) -- 标签的Y坐标。z (
float) -- 标签的Z坐标。anchor_x (
Literal['left','center','right']) -- X坐标的锚点。anchor_y (
Literal['top','bottom','center','baseline']) -- Y坐标的锚点。rotation (
float) -- 以度数为单位旋转标签的量。正值将是顺时针旋转，负值将导致逆时针旋转。multiline (
bool) -- 如果为False，则忽略新元素和段落字符，并且文本不会进行单词包装。如果为True，则仅在 wrap_lines 是真的。group (
Group|None) -- 可选组，用于此文本布局使用的所有内部组的父级。 请注意，具有相同组的布局将在批处理中同时渲染。program (
ShaderProgram|None) -- 可选使用的图形着色器。将影响布局中的所有字形。wrap_lines (
bool) -- 如果为真且 multiline 为True，则文本将使用指定的宽度进行单词包装。init_document (
bool) -- 如果为True，文档将被初始化。如果要进行子分类，那么您可能希望通过更改为False来避免重复初始化。
- begin_update() None
表示即将对布局或文档进行多项更改。
调用之间对布局或文档的更改 begin_update 和 end_update 不要触发任何代价高昂的文本重新布局。在以下情况下执行所有更改的重新布局 end_update 被称为。
请注意，在 begin_update 和 end_update 调用、值，如 content_width 和 content_height 未定义(即，它们可能会更新，也可能不会更新，以反映最新的更改)。
- 返回类型:
- draw() None
Draw this text layout. :rtype:
None备注
如果向构造函数提供批处理，则此方法的性能非常差。如果将此布局添加到批处理中，最好只使用该批处理的绘制方法。
备注
如果这不是它自己的批处理，则不会绘制InlineElement。
- get_as_texture( ) Texture
利用
Framebuffer将当前布局绘制到纹理中。警告
只有当您了解纹理生成如何影响您的应用程序时，才建议使用。使用不当会导致纹理内存泄漏和性能下降。
备注
不包括InlineElements。
- 返回类型:
- 返回:
绘制了布局的新纹理。
Added in version 2.0.11.
- on_delete_text(start: int, end: int) None
的事件处理程序 AbstractDocument.on_delete_text 。
事件处理程序由文本布局绑定；应用程序不需要与此方法交互。
- 返回类型:
- on_insert_text(start: int, text: str) None
的事件处理程序 AbstractDocument.on_insert_text 。
事件处理程序由文本布局绑定；应用程序不需要与此方法交互。
- 返回类型:
- property anchor_x: Literal['left', 'center', 'right']
水平锚点对齐。
此属性确定
x协调。支持以下值：
"left"(违约)X坐标给出布局左边缘的位置。
"center"X坐标给出了布局中心的位置。
"right"X坐标给出布局的右边缘的位置。
为了计算由该路线产生的位置，布局的宽度被视为
width如果multiline是真的并且wrap_lines为True，否则为content_width。
- property anchor_y: Literal['top', 'bottom', 'center', 'baseline']
垂直锚点对齐。
此属性确定
y协调。支持以下值：
"top"Y坐标给出布局顶边的位置。
"center"Y坐标给出了布局中心的位置。
"baseline"Y坐标提供布局中第一行文本的基线位置。
"bottom"(违约)Y坐标提供布局的底边的位置。
为了计算由该路线产生的位置，布局的高度被视为以下最小的
height和content_height。另请参阅
content_valign。
- property content_valign: Literal['left', 'center', 'top']
较大布局框内内容的垂直对齐方式。
此属性确定以下情况时内容在布局框中的位置
content_height小于height。支持以下值：
top(违约)内容与布局框的顶部对齐。
center内容在布局框中垂直居中。
bottom内容与布局框底部对齐。
此属性在以下情况下不起作用
content_height大于height(在这种情况下，内容与顶部对齐)或height是None(在这种情况下，没有垂直布局框尺寸)。
- property document: AbstractDocument
要显示的文档。
为
IncrementalTextLayout就地修改文档比替换布局上的文档实例效率高得多。
- property height: int | None
定义的布局最大高度（以像素为单位），或无。
什么时候 height 不是None，则它会影响文本的位置
anchor_y和content_valign都被使用过。
- property multiline: bool
设置是否启用多行布局。
如果
multiline为False，则忽略白线和段落字符，并且文本不进行单词包装。如果为True，则文本仅在wrap_lines是真的。
- property program: ShaderProgram
分配给此布局的ShaderProgram。
如果设置，着色器将影响所有字形。InlineElements不会受到影响。
- class TextLayoutGroup
创建文本布局渲染组。
当
Label被创建;应用程序通常不需要显式创建它。
- get_default_decoration_shader() ShaderProgram
布局中用于眼线和背景装饰效果的默认材质球。
- 返回类型:
- get_default_image_layout_shader() ShaderProgram
用于InlineElement图像的默认着色器。用于通过标签插入图像的HTML标签<img>。
- 返回类型:
- get_default_layout_shader() ShaderProgram
用于布局中所有字形的默认材质球。
- 返回类型: