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，则该行不会换行，并且可能会溢出布局宽度。char和word样式是从pyglet1.2开始的。
其他属性可用于在文档中存储其他样式信息；内置文本类将忽略这些属性。
在 1.1 版本加入.
- class IncrementalTextDecorationGroup(program: ShaderProgram, order: int = 0, parent: graphics.Group | None = None)
- scissor_area = (0, 0, 0, 0)
- class IncrementalTextLayout(document: AbstractDocument, width: int, height: int, x: float = 0, y: float = 0, z: float = 0, anchor_x: AnchorX = 'left', anchor_y: AnchorY = 'bottom', rotation: float = 0, multiline: bool = False, dpi: float | None = None, batch: Batch | None = None, group: Group | None = None, program: ShaderProgram | None = None, wrap_lines: bool = True)
适合交互编辑和/或滚动大型文档的显示文本。
不像
TextLayout()和ScrollableTextLayout时，此类仅为可见的文本行生成顶点列表。滚动文档时，会根据需要删除和创建顶点列表，以将视频内存使用量保持在最低水平并提高渲染速度。对文档的更改会迅速反映在此版面中，因为只有受影响的行(S)会被重排。使用 begin_update 和 end_update 以进一步减少所需的处理量。
布局还可以显示文本选择(具有不同背景颜色的文本)。这个
Caret类实现可见的文本光标，并提供用于滚动、选择和编辑增量文本布局中的文本的事件处理程序。- decoration_class
- group_class
- get_point_from_position(position, line=None)
获取文档中某个位置的X、Y坐标。
结束一条线的位置有一个模糊点：它可以是这条线的终点，也可以是下一条线的起点。您可以选择指定行索引来消除大小写的歧义。
生成的Y坐标提供了直线的基线。
- get_position_on_line(line_idx: int, x: float) int
获取给定行索引和X坐标的最接近文档位置。
- 参数:
- line集成
行索引。
- x集成
X坐标。
- 返回类型:
- 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()
部分或全部布局文本已重排。
文本回流是由文档编辑或版面大小更改引起的。对版面位置或活动选定内容的更改以及某些文档编辑(如文本颜色)不会导致重排。
处理此事件可更新图形元素的位置，该位置取决于字形或线条的布局位置。
- 活动:
- on_style_text(start: int, end: int, attributes: dict[str, Any]) None
的事件处理程序 AbstractDocument.on_style_text 。
事件处理程序由文本布局绑定；应用程序不需要与此方法交互。
- set_selection(start: int, end: int) None
设置文本选择范围。
如果
start相等end不会显示任何选择。- 参数:
- start集成
选定内容的起始字符位置。
- end集成
选择结束，独家。
- 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 = ['on_layout_update', 'on_translation_update']
- glyphs: List[Any]
- property height: int
定义的布局最大高度(以像素为单位)，或无
什么时候 height 不是None，则它会影响文本的位置
anchor_y和content_valign都被使用过。- 类型:
集成
- invalid_flow: _InvalidRange
- invalid_glyphs: _InvalidRange
- invalid_lines: _InvalidRange
- invalid_style: _InvalidRange
- invalid_vertex_lines: _InvalidRange
- lines: List[_Line]
- property multiline: bool
设置是否启用多行布局。
如果Multiline为FALSE，则会忽略换行符和段落字符，并且文本不会自动换行。如果为True，则文本仅在 wrap_lines 是真的。
- 类型:
布尔尔
- owner_runs: runlist.RunList
- property selection_background_color: Tuple[int, int, int, int]
活动选定内容的背景色。
该颜色是一个RGBA元组，其组件在范围内 [0, 255] 。
- 类型:
(int，int)
- property selection_color: Tuple[int, int, int, int]
活动选定内容的文本颜色。
该颜色是一个RGBA元组，其组件在范围内 [0, 255] 。
- 类型:
(int，int)
- property view_x: int
水平滚动偏移量。
初始值为0，文本的左边缘将接触布局边界的左侧。如果为正值，文本将向右滚动。值将自动裁剪到范围内
[0, content_width - width]- 类型:
集成
- property view_y: int
垂直滚动偏移量。
初始值为0，文本的顶部将接触到布局边界的顶部(除非内容高度小于布局高度，在这种情况下 content_valign 是使用的)。
负值会导致文本向上“滚动”。范围外的值
[height - content_height, 0]会自动在范围内进行裁剪。- 类型:
集成
- visible_lines: _InvalidRange
- class IncrementalTextLayoutGroup(texture: Texture, program: ShaderProgram, order: int = 1, parent: graphics.Group | None = None)
- scissor_area = (0, 0, 0, 0)
- class ScrollableTextDecorationGroup(program: ShaderProgram, order: int = 0, parent: graphics.Group | None = None)
-
- scissor_area = (0, 0, 0, 0)
- class ScrollableTextLayout(document: AbstractDocument, width: int, height: int, x: float = 0, y: float = 0, z: float = 0, anchor_x: AnchorX = 'left', anchor_y: AnchorY = 'bottom', rotation: float = 0, multiline: bool = False, dpi: float | None = None, batch: Batch | None = None, group: graphics.Group | None = None, program: ShaderProgram | None = None, wrap_lines: bool = True)
在可滚动的视区中显示文本。
此类不显示滚动条或处理滚动事件；它只剪辑将绘制在
TextLayout()给出的布局的边界 x ， y ， width 和 height ；并将文本偏移滚动偏移量。使用 view_x 和 view_y 在视口中滚动文本。
- decoration_class
- group_class
- 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(texture: Texture, program: ShaderProgram, order: int = 1, parent: graphics.Group | None = None)
-
- scissor_area = (0, 0, 0, 0)
- class TextDecorationGroup(program: ShaderProgram, order: int = 0, parent: graphics.Group | None = None)
- class TextLayout(document: AbstractDocument, width: int | None = None, height: int | None = None, x: float = 0, y: float = 0, z: float = 0, anchor_x: AnchorX = 'left', anchor_y: AnchorY = 'bottom', rotation: float = 0, multiline: bool = False, dpi: float | None = None, batch: Batch = None, group: graphics.Group | None = None, program: ShaderProgram | None = None, wrap_lines: bool = True, init_document: bool = True)
布局和显示文档。
此类用于显示不定期更改的文档--任何更改都需要花费一些时间来重新布局完整的文档并重新生成所有顶点列表。
这个类的好处是纹理状态在这个类的所有布局之间共享。是时候画一张了
TextLayout()可能与画一个的时间大致相同IncrementalTextLayout；但是画了十张TextLayout()一批对象比绘制十个增量或可滚动的文本布局要快得多。Label()和HTMLLabel()为此类提供一个方便的接口。- 变量:
- content_width集成
布局中文本的计算宽度。如果换行失败，这可能会溢出所需的宽度。
- content_height集成
计算出的布局中文本高度。
- group_class~pyglet.graphics.Group
顶层渲染组。
- background_decoration_group~pyglet.graphics.Group
背景色的渲染组。
- foreground_decoration_group~pyglet.graphics.Group
字形下划线的渲染组。
- decoration_class
- group_class
TextLayoutGroup的别名
- begin_update() None
表示即将对布局或文档进行多项更改。
调用之间对布局或文档的更改 begin_update 和 end_update 不要触发任何代价高昂的文本重新布局。在以下情况下执行所有更改的重新布局 end_update 被称为。
请注意，在 begin_update 和 end_update 调用、值，如 content_width 和 content_height 未定义(即，它们可能会更新，也可能不会更新，以反映最新的更改)。
- draw() None
绘制此文本布局。
请注意，如果将批处理提供给构造函数，则此方法的性能会非常差。如果将此布局添加到批次中，则理想情况下应仅使用批次的Draw方法。
如果这不是它自己的批处理，则不会绘制InlineElement。
- get_as_texture(min_filter=9728, mag_filter=9728) Texture
返回绘制了TextLayout的纹理。每次调用此函数都会返回一个新纹理。~警告：仅当您了解纹理生成如何影响您的应用程序时，才建议使用。
- 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_style_text(start: int, end: int, attributes: dict[str, Any]) None
的事件处理程序 AbstractDocument.on_style_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就地修改文档比替换布局上的文档实例效率高得多。- 类型:
AbstractDocument
- group_cache: Dict[Texture, graphics.Group]
- property height: int | None
定义的布局最大高度(以像素为单位)，或无
什么时候 height 不是None，则它会影响文本的位置
anchor_y和content_valign都被使用过。- 类型:
集成
- property multiline: bool
设置是否启用多行布局。
如果Multiline为FALSE，则会忽略换行符和段落字符，并且文本不会自动换行。如果为True，则文本仅在 wrap_lines 是真的。
- 类型:
布尔尔
- property program: ShaderProgram
分配给此布局的ShaderProgram。
如果设置该着色器，则该着色器将影响除InlineElement之外的所有文本布局。
- 类型:
- class TextLayoutGroup(texture: Texture, program: ShaderProgram, order: int = 1, parent: graphics.Group | None = None)
- get_default_decoration_shader() ShaderProgram
- get_default_image_layout_shader() ShaderProgram
- get_default_layout_shader() ShaderProgram