pyglet.text.document

文本布局使用的格式化和非格式化文档界面。

抽象表象

Piglet中的带样式的文本由 AbstractDocument 类，这些类独立于文本的加载或呈现方式来管理文本和样式的状态表示形式。

文档由文档文本(Unicode字符串)和一组命名样式范围组成。例如，考虑以下(人工)示例：

0    5   10   15   20
The cat sat on the mat.
+++++++        +++++++    "bold"
            ++++++      "italic"

如果要呈现此示例，则“the cat”和“the mat”将以粗体显示，而“on”将以斜体显示。注意，第二个“the”既是粗体，也是斜体。

在本例中记录的文档样式为 "bold" 范围(0-7、15-22)和 "italic" 超出范围(12-18)。允许重叠样式；与HTML和其他结构化标记不同，范围不需要嵌套。

该文档不了解 "bold" 或 "italic" ，它只存储样式名称。pyglet布局类赋予这些样式名称以呈现方式的含义；但您也可以自由地发明自己的样式名称(布局类将忽略这些名称)。这对于标记文档中感兴趣的区域或维护对源材料的引用非常有用。

除了文本之外，文档还可以包含由表示的任意元素 InlineElement 。内联元素的行为类似于文档中的单个字符，但可以由应用程序呈现。

换段符

段落分隔符用换行符(U+0010)标记。也可以使用Unicode换段符(U+2029)。

换行符(U+2028)可用于强制段落内的换行符。

有关更多信息，请参阅Unicode建议UTR #13：https://www.unicode.org/standard/reports/tr13/tr13-5.html。

文档类

任何类实现 AbstractDocument 如上所述提供到文档模型的接口。理论上，一个结构化的文档，如HTML或XML，可以导出这个模型，尽管由pyglet提供的类只实现非结构化的文档。

这个 UnformattedDocument 类假定在整个文档上设置了任何样式集。因此，无论在设置 "bold" 属性，例如，整个文档都将收到该样式。

这个 FormattedDocument 类直接实现文档模型，使用 RunList 类来高效地表示样式运行。

样式属性

pyglet可以识别以下字符样式属性名称：

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 用于无背景填充。

pyglet可以识别以下段落样式属性名称。请注意，文档对段落样式的处理与对字符样式的处理没有什么不同：应用程序负责在整个段落上设置样式，否则结果不确定。

align: left (默认)， center 或 right 。
indent: 要在第一个字符之前插入的附加水平空格
leading: 要在段落内的连续行之间插入的附加空格(以磅为单位)。默认为0。
line_spacing: 段落中连续基线之间的距离，以磅为单位。默认为 None ，它会根据字体的升降自动计算每行的最紧行距。
margin_left: 左段落边距，以像素为单位。
margin_right: 右侧段落边距，以像素为单位。
margin_top: 段落上方的边距，以像素为单位。
margin_bottom: 段落下方的边距，以像素为单位。相邻页边距不会折叠。
tab_stops: 水平制表位列表，以像素为单位，从文本布局的左边缘开始测量。默认为空列表。当制表位用完时，它们隐式地以50像素的间隔继续。
wrap: 布尔型。如果为True(默认值)，则文本在布局的宽度内换行。

其他属性可用于在文档中存储附加的样式信息；内置的文本类将忽略这些信息。

所有样式属性(包括文档中不存在的样式属性)默认为 None (包括上面列出的所谓的“布尔”样式)。A的含义是 None 样式依赖于样式和应用程序。

class AbstractDocument

所有人都使用的抽象文档接口 pyglet.text 上课。

此类可以被重写，以将Piglet与第三方文档格式接口。根据所提供的一个具体类来实现文档格式可能会更容易 FormattedDocument 或 UnformattedDocument 。

__init__(text: str = '') → None

用文本初始化文档。

参数:: text (str) -- 初始文本字符串。

delete_text(start: int, end: int) → None

从文档中删除文本。

调度一个 on_delete_text() 事件。

参数:

start (int) -- 要从中删除的起始字符位置。
end (int) -- 要删除的结束字符位置(独占)。

返回类型:

None

get_element(position: int) → InlineElement

获取指定位置的元素。

参数:: position (int) -- 元素在文档中的位置。
返回类型:: InlineElement

abstract get_font( position: int, dpi: int | None = None, ) → Font

获取在给定位置使用的字体实例。

看见:

get_font_runs

参数:

position (int) -- 要查询的单据的字符位置。
dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。

返回类型:

Font

abstract get_font_runs( dpi: int | None = None, ) → AbstractRunIterator

获取样式迭代器 pyglet.font.Font 文档中使用的实例。

字体实例是通过检查 font_name ， font_size ， bold 和 italic 样式属性。

参数:: dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。
返回类型:: AbstractRunIterator

get_paragraph_end(pos: int) → int

从字符位置获取段落的结束位置。

返回类型:: int

get_paragraph_start(pos: int) → int

从字符位置获取段落的开始位置。

返回类型:: int

abstract get_style(attribute: str, position: int = 0) → Any

获取给定位置的属性样式。

参数:

attribute (str) -- 要查询的样式属性的名称。
position (int) -- 要查询的单据的字符位置。

返回类型:

Any

返回:

为给定位置的属性设置的样式。

get_style_range(attribute: str, start: int, end: int) → Any

获取给定范围内的属性样式。

如果款式在整个范围内有所不同， STYLE_INDETERMINATE 是返回的。

参数:

attribute (str) -- 要查询的样式属性的名称。
start (int) -- 开始字符位置。
end (int) -- 结束字符位置(独占)。

返回类型:

Any

返回:

为给定范围内的属性设置的样式，或 STYLE_INDETERMINATE 如果设置了多个值。

abstract get_style_runs( attribute: str, ) → AbstractRunIterator

获取给定样式属性的样式迭代器。

参数:: attribute (str) -- 要查询的样式属性的名称。
返回类型:: AbstractRunIterator

insert_element( position: int, element: InlineElement, attributes: dict[str, Any] | None = None, ) → None

在文档中插入元素。

请参阅 InlineElement 有关用法的详细信息，请参阅类文档。

参数:

position (int) -- 文档内的字符插入点。
element (InlineElement) -- 要插入的元素。
attributes (dict[str, Any] | None) -- dict可选词典，提供插入文本的命名样式属性。

返回类型:

None

insert_text( start: int, text: str, attributes: dict[str, Any] | None = None, ) → None

在文档中插入文本。

调度一个 on_insert_text() 事件。

参数:

start (int) -- 文档内的字符插入点。
text (str) -- 要插入的文本。
attributes (dict[str, Any] | None) -- 给出插入文本的命名样式属性的可选词典。

返回类型:

None

on_delete_text(start: int, end: int) → None

文本已从文档中删除。

参数:

start (int) -- 已删除文本的起始字符位置。
end (int) -- 删除文本的结束字符位置(不包括)。

活动:

返回类型:

None

on_insert_text(start: int, text: str) → None

文本已插入到文档中。

参数:

start (int) -- 文档内的字符插入点。
text (str) -- 插入的文本。

活动:

返回类型:

None

on_style_text( start: int, end: int, attributes: dict[str, Any] | None, ) → None

文本字符样式已修改。

参数:

start (int) -- 修改后的文本的起始字符位置。
end (int) -- 修改文本的结束字符位置(不包括)。
attributes (dict[str, Any] | None) -- 给出更新后的文本命名样式属性的词典。

活动:

返回类型:

None

set_paragraph_style( start: int, end: int, attributes: dict[str, Any], ) → None

设置一系列段落的样式。

这是一种方便的方法 set_style 这会将字符范围与封闭的段落(S)对齐。

调度一个 on_style_text() 事件。

参数:

start (int) -- 开始字符位置。
end (int) -- 结束字符位置(独占)。
attributes (dict[str, Any]) -- 给出段落命名样式属性的词典。

返回类型:

None

set_style( start: int, end: int, attributes: dict[str, Any], ) → None

设置文档开始和结束之间的范围的文本样式。

调度一个 on_style_text() 事件。

参数:

start (int) -- 开始字符位置。
end (int) -- 结束字符位置(独占)。
attributes (dict[str, Any]) -- 给出文本的命名样式属性的词典。

返回类型:

None

event_types: list = ['on_insert_text', 'on_delete_text', 'on_style_text']

property text: str

文档文本。

为实现高效的增量更新，请使用 insert_text() 和 delete_text() 方法，而不是替换此属性。

class FormattedDocument

维护文本格式的文档的简单实现。

根据中的描述应用对文本样式的更改 AbstractDocument 。所有样式默认为 None 。

__init__(text: str = '') → None

用文本初始化文档。

参数:: text (str) -- 初始文本字符串。

get_element_runs() → _ElementIterator

返回类型:: _ElementIterator

get_font( position: int, dpi: int | None = None, ) → Font

获取在给定位置使用的字体实例。

看见:

get_font_runs

参数:

position (int) -- 要查询的单据的字符位置。
dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。

返回类型:

Font

get_font_runs( dpi: int | None = None, ) → _FontStyleRunsRangeIterator

获取样式迭代器 pyglet.font.Font 文档中使用的实例。

字体实例是通过检查 font_name ， font_size ， bold 和 italic 样式属性。

参数:: dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。
返回类型:: _FontStyleRunsRangeIterator

get_style(attribute: str, position: int = 0) → Any | None

获取给定位置的属性样式。

参数:

attribute (str) -- 要查询的样式属性的名称。
position (int) -- 要查询的单据的字符位置。

返回类型:

Any | None

返回:

为给定位置的属性设置的样式。

get_style_runs( attribute: str, ) → RunIterator | _NoStyleRangeIterator

获取给定样式属性的样式迭代器。

参数:: attribute (str) -- 要查询的样式属性的名称。
返回类型:: RunIterator | _NoStyleRangeIterator

class InlineElement

位于格式化文档内的任意行内元素。

元素的行为类似于文档中的单个字形。它们是通过水平推进、上升到基线之上、下降到基线以下来衡量的。

pyglet布局类在布局中为元素保留空间，并调用元素的方法以确保它们呈现在适当的位置。

如果元素的大小（任何 advance ， ascent ，或 descent 变量）被修改时，应用程序有责任触发受影响布局中适当区域的回流。这可以通过强制更改元素位置的样式来实现。

__init__(ascent: int, descent: int, advance: int) → None

初始化元素。

参数:

ascent (int) -- 元素在基线之上的上升，以像素为单位。
descent (int) -- 元素在基线以下的下降，以像素为单位。通常是负面的。
advance (int) -- 元素的宽度，以像素为单位。

abstract place( layout: TextLayout, x: float, y: float, z: float, line_x: float, line_y: float, rotation: float, visible: bool, anchor_x: float, anchor_y: float, ) → None

返回类型:: None

abstract remove(layout: TextLayout) → None

返回类型:: None

abstract update_anchor(anchor_x: float, anchor_y: float) → None

返回类型:: None

abstract update_color(color: list[int]) → None

返回类型:: None

abstract update_rotation(rotation: float) → None

返回类型:: None

abstract update_translation(x: float, y: float, z: float) → None

返回类型:: None

abstract update_view_translation(translate_x: float, translate_y: float) → None

返回类型:: None

abstract update_visibility(visible: bool) → None

返回类型:: None

advance: int

ascent: int

descent: int

property position: int | None

文档中的字符位置。

由其所在的布局决定。将返回 None 如果还没有放置。

class UnformattedDocument

在所有文本上具有统一样式的文档。

对文档中文本样式的更改会影响整个文档。为方便起见， position 因此，可以省略样式方法的参数。

__init__(text: str = '') → None: 使用字符串创建未格式化的文档。

get_element_runs() → ConstRunIterator

返回类型:: ConstRunIterator

get_font( position: int | None = None, dpi: int | None = None, ) → Font

获取在给定位置使用的字体实例。

看见:

get_font_runs

参数:

position (int | None) -- 要查询的单据的字符位置。
dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。

返回类型:

Font

get_font_runs( dpi: int | None = None, ) → ConstRunIterator

获取样式迭代器 pyglet.font.Font 文档中使用的实例。

字体实例是通过检查 font_name ， font_size ， bold 和 italic 样式属性。

参数:: dpi (int | None) -- 可选分辨率来构造字体。 :see: load() 。
返回类型:: ConstRunIterator

get_style( attribute: str, position: int | None = None, ) → Any

获取给定位置的属性样式。

参数:

attribute (str) -- 要查询的样式属性的名称。
position (int | None) -- 要查询的单据的字符位置。

返回类型:

Any

返回:

为给定位置的属性设置的样式。

get_style_runs( attribute: str, ) → ConstRunIterator

获取给定样式属性的样式迭代器。

参数:: attribute (str) -- 要查询的样式属性的名称。
返回类型:: ConstRunIterator

set_paragraph_style( start: int, end: int, attributes: dict[str, Any], ) → None

设置一系列段落的样式。

这是一种方便的方法 set_style 这会将字符范围与封闭的段落(S)对齐。

调度一个 on_style_text() 事件。

参数:

start (int) -- 开始字符位置。
end (int) -- 结束字符位置(独占)。
attributes (dict[str, Any]) -- 给出段落命名样式属性的词典。

返回类型:

None

set_style( start: int, end: int, attributes: dict[str, Any], ) → None

设置文档开始和结束之间的范围的文本样式。

调度一个 on_style_text() 事件。

参数:

start (int) -- 开始字符位置。
end (int) -- 结束字符位置(独占)。
attributes (dict[str, Any]) -- 给出文本的命名样式属性的词典。

返回类型:

None

STYLE_INDETERMINATE = 'indeterminate': 样式属性在文档中具有多个值。