pyglet.text.document

Formatted and unformatted document interfaces used by text layout.

Abstract representation

Styled text in pyglet is represented by one of the AbstractDocument classes, which manage the state representation of text and style independently of how it is loaded or rendered.

A document consists of the document text (a Unicode string) and a set of named style ranges. For example, consider the following (artificial) example:

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

If this example were to be rendered, “The cat” and “the mat” would have a weight set (“bold”, “thin”, etc.), and “on the” would be in italics. Note that the second “the” is both weighted and italic.

The document styles recorded for this example would be a specific "weight" over ranges (0-7) & (15-22) and "italic" over range (12-18). Overlapping styles are permitted; unlike HTML and other structured markup, the ranges need not be nested.

The document has no knowledge of the semantics of "weight" names or "italic", it stores only the style names. The pyglet layout classes give meaning to these style names in the way they are rendered; but you are also free to invent your own style names (which will be ignored by the layout classes). This can be useful to tag areas of interest in a document, or maintain references back to the source material.

As well as text, the document can contain arbitrary elements represented by InlineElement. An inline element behaves like a single character in the document, but can be rendered by the application.

Paragraph breaks

Paragraph breaks are marked with a “newline” character (U+0010). The Unicode paragraph break (U+2029) can also be used.

Line breaks (U+2028) can be used to force a line break within a paragraph.

See Unicode recommendation UTR #13 for more information: https://www.unicode.org/standard/reports/tr13/tr13-5.html.

Document classes

Any class implementing AbstractDocument provides an interface to a document model as described above. In theory a structured document such as HTML or XML could export this model, though the classes provided by pyglet implement only unstructured documents.

The UnformattedDocument class assumes any styles set are set over the entire document. So, regardless of the range specified when setting a "weight" style attribute, for example, the entire document will receive that style.

The FormattedDocument class implements the document model directly, using the RunList class to represent style runs efficiently.

Style attributes

The following character style attribute names are recognised by pyglet:

font_name

Font family name, as given to pyglet.font.load().

font_size

Font size, in points.

weight

String.

italic

Boolean.

underline

4-tuple of ints in range (0, 255) giving RGBA underline color, or None (default) for no underline.

kerning

Additional space to insert between glyphs, in points. Defaults to 0.

baseline

Offset of glyph baseline from line baseline, in points. Positive values give a superscript, negative values give a subscript. Defaults to 0.

color

4-tuple of ints in range (0, 255) giving RGBA text color

background_color

4-tuple of ints in range (0, 255) giving RGBA text background color; or None for no background fill.

The following paragraph style attribute names are recognised by pyglet. Note that paragraph styles are handled no differently from character styles by the document: it is the application’s responsibility to set the style over an entire paragraph, otherwise results are undefined.

align

left (default), center or right.

indent

Additional horizontal space to insert before the first

leading

Additional space to insert between consecutive lines within a paragraph, in points. Defaults to 0.

line_spacing

Distance between consecutive baselines in a paragraph, in points. Defaults to None, which automatically calculates the tightest line spacing for each line based on the font ascent and descent.

margin_left

Left paragraph margin, in pixels.

margin_right

Right paragraph margin, in pixels.

margin_top

Margin above paragraph, in pixels.

margin_bottom

Margin below paragraph, in pixels. Adjacent margins do not collapse.

tab_stops

List of horizontal tab stops, in pixels, measured from the left edge of the text layout. Defaults to the empty list. When the tab stops are exhausted, they implicitly continue at 50 pixel intervals.

wrap

Boolean. If True (the default), text wraps within the width of the layout.

Other attributes can be used to store additional style information within the document; it will be ignored by the built-in text classes.

All style attributes (including those not present in a document) default to None (including the so-called “boolean” styles listed above). The meaning of a None style is style- and application-dependent.

class AbstractDocument

Abstract document interface used by all pyglet.text classes.

This class can be overridden to interface pyglet with a third-party document format. It may be easier to implement the document format in terms of one of the supplied concrete classes FormattedDocument or UnformattedDocument.

__init__(text: str = '') → None

Initialize a document with text.

Parameters:

text (str) – Initial text string.

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

Delete text from the document.

Dispatches an on_delete_text() event.

Parameters:

  • start (int) – Starting character position to delete from.

  • end (int) – Ending character position to delete to (exclusive).

Return type:

None

get_element(position: int) → InlineElement

Get the element at a specified position.

Parameters:

position (int) – Position in the document of the element.

Return type:

InlineElement

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

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

  • position (int) – Character position of document to query.

  • dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

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

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, weight and italic style attributes.

Parameters:

dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

AbstractRunIterator

get_paragraph_end(pos: int) → int

Get the end position of a paragraph from the character position.

Return type:

int

get_paragraph_start(pos: int) → int

Get the starting position of a paragraph from the character position.

Return type:

int

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

Get an attribute style at the given position.

Parameters:

  • attribute (str) – Name of style attribute to query.

  • position (int) – Character position of document to query.

Return type:

Any

Returns:

The style set for the attribute at the given position.

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

Get an attribute style over the given range.

If the style varies over the range, STYLE_INDETERMINATE is returned.

Parameters:

  • attribute (str) – Name of style attribute to query.

  • start (int) – Starting character position.

  • end (int) – Ending character position (exclusive).

Return type:

Any

Returns:

The style set for the attribute over the given range, or STYLE_INDETERMINATE if more than one value is set.

abstract get_style_runs(
attribute: str,
) → AbstractRunIterator

Get a style iterator over the given style attribute.

Parameters:

attribute (str) – Name of style attribute to query.

Return type:

AbstractRunIterator

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

Insert a element into the document.

See the InlineElement class documentation for details of usage.

Parameters:

  • position (int) – Character insertion point within document.

  • element (InlineElement) – Element to insert.

  • attributes (dict[str, Any] | None) – dict Optional dictionary giving named style attributes of the inserted text.

Return type:

None

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

Insert text into the document.

Dispatches an on_insert_text() event.

Parameters:

  • start (int) – Character insertion point within document.

  • text (str) – Text to insert.

  • attributes (dict[str, Any] | None) – Optional dictionary giving named style attributes of the inserted text.

Return type:

None

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

Text was deleted from the document.

Parameters:

  • start (int) – Starting character position of deleted text.

  • end (int) – Ending character position of deleted text (exclusive).

Event:

Return type:

None

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

Text was inserted into the document.

Parameters:

  • start (int) – Character insertion point within document.

  • text (str) – The text that was inserted.

Event:

Return type:

None

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

Text character style was modified.

Parameters:

  • start (int) – Starting character position of modified text.

  • end (int) – Ending character position of modified text (exclusive).

  • attributes (dict[str, Any] | None) – Dictionary giving updated named style attributes of the text.

Event:

Return type:

None

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

Set the style for a range of paragraphs.

This is a convenience method for set_style that aligns the character range to the enclosing paragraph(s).

Dispatches an on_style_text() event.

Parameters:

  • start (int) – Starting character position.

  • end (int) – Ending character position (exclusive).

  • attributes (dict[str, Any]) – Dictionary giving named style attributes of the paragraphs.

Return type:

None

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

Set text style of a range between start and end of the document.

Dispatches an on_style_text() event.

Parameters:

  • start (int) – Starting character position.

  • end (int) – Ending character position (exclusive).

  • attributes (dict[str, Any]) – Dictionary giving named style attributes of the text.

Return type:

None

event_types: list = ['on_insert_text', 'on_delete_text', 'on_style_text']
property text: str

Document text.

For efficient incremental updates, use the insert_text() and delete_text() methods instead of replacing this property.

class FormattedDocument

Simple implementation of a document that maintains text formatting.

Changes to text style are applied according to the description in AbstractDocument. All styles default to None.

__init__(text: str = '') → None

Initialize a document with text.

Parameters:

text (str) – Initial text string.

get_element_runs() → _ElementIterator
Return type:

_ElementIterator

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

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

  • position (int) – Character position of document to query.

  • dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

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

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, weight and italic style attributes.

Parameters:

dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

_FontStyleRunsRangeIterator

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

Get an attribute style at the given position.

Parameters:

  • attribute (str) – Name of style attribute to query.

  • position (int) – Character position of document to query.

Return type:

Any | None

Returns:

The style set for the attribute at the given position.

get_style_runs(
attribute: str,
) → RunIterator | _NoStyleRangeIterator

Get a style iterator over the given style attribute.

Parameters:

attribute (str) – Name of style attribute to query.

Return type:

RunIterator | _NoStyleRangeIterator

class InlineElement

Arbitrary inline element positioned within a formatted document.

Elements behave like a single glyph in the document. They are measured by their horizontal advance, ascent above the baseline, and descent below the baseline.

The pyglet layout classes reserve space in the layout for elements and call the element’s methods to ensure they are rendered at the appropriate position.

If the size of an element (any of the advance, ascent, or descent variables) is modified it is the application’s responsibility to trigger a reflow of the appropriate area in the affected layouts. This can be done by forcing a style change over the element’s position.

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

Initialize the element.

Parameters:

  • ascent (int) – Ascent of the element above the baseline, in pixels.

  • descent (int) – Descent of the element below the baseline, in pixels. Typically negative.

  • advance (int) – Width of the element, in pixels.

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
Return type:

None

abstract remove(layout: TextLayout) → None
Return type:

None

abstract update_anchor(anchor_x: float, anchor_y: float) → None
Return type:

None

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

None

abstract update_rotation(rotation: float) → None
Return type:

None

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

None

abstract update_view_translation(translate_x: float, translate_y: float) → None
Return type:

None

abstract update_visibility(visible: bool) → None
Return type:

None

advance: int
ascent: int
descent: int
property position: int | None

Character position within the document.

Determined by the layout it is in. Will return None if it has not been placed.

class UnformattedDocument

A document having uniform style over all text.

Changes to the style of text within the document affects the entire document. For convenience, the position parameters of the style methods may therefore be omitted.

__init__(text: str = '') → None

Create unformatted document with a string.

get_element_runs() → ConstRunIterator
Return type:

ConstRunIterator

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

Get the font instance used at the given position.

See:

get_font_runs

Parameters:

  • position (int | None) – Character position of document to query.

  • dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

Font

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

Get a style iterator over the pyglet.font.Font instances used in the document.

The font instances are created on-demand by inspection of the font_name, font_size, weight and italic style attributes.

Parameters:

dpi (int | None) – Optional resolution to construct fonts at. :see: load().

Return type:

ConstRunIterator

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

Get an attribute style at the given position.

Parameters:

  • attribute (str) – Name of style attribute to query.

  • position (int | None) – Character position of document to query.

Return type:

Any

Returns:

The style set for the attribute at the given position.

get_style_runs(
attribute: str,
) → ConstRunIterator

Get a style iterator over the given style attribute.

Parameters:

attribute (str) – Name of style attribute to query.

Return type:

ConstRunIterator

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

Set the style for a range of paragraphs.

This is a convenience method for set_style that aligns the character range to the enclosing paragraph(s).

Dispatches an on_style_text() event.

Parameters:

  • start (int) – Starting character position.

  • end (int) – Ending character position (exclusive).

  • attributes (dict[str, Any]) – Dictionary giving named style attributes of the paragraphs.

Return type:

None

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

Set text style of a range between start and end of the document.

Dispatches an on_style_text() event.

Parameters:

  • start (int) – Starting character position.

  • end (int) – Ending character position (exclusive).

  • attributes (dict[str, Any]) – Dictionary giving named style attributes of the text.

Return type:

None

STYLE_INDETERMINATE = 'indeterminate'

The style attribute takes on multiple values in the document.