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.
+++++++ +++++++ "bold"
++++++ "italic"
If this example were to be rendered, “The cat” and “the mat” would be in bold, and “on the” in italics. Note that the second “the” is both bold and italic.
The document styles recorded for this example would be "bold"
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 "bold"
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: http://unicode.org/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 "bold"
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.
bold
Boolean.
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
orright
.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.
New in version 1.1.
- class AbstractDocument(text='')
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
orUnformattedDocument
.- delete_text(start, end)
Delete text from the document.
- Parameters:
- startint
Starting character position to delete from.
- endint
Ending character position to delete to (exclusive).
- get_element(position)
Get the element at a specified position.
- Parameters:
- positionint
Position in the document of the element.
- Return type:
- get_font(position, dpi=None)
Get the font instance used at the given position.
- See:
get_font_runs
- Parameters:
- positionint
Character position of document to query.
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
pyglet.font.Font
- Returns:
The font at the given position.
- get_font_runs(dpi=None)
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
,bold
anditalic
style attributes.- Parameters:
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
AbstractRunIterator
- get_paragraph_end(pos)
Get the end position of a paragraph.
- Parameters:
- posint
Character position within paragraph.
- Return type:
- get_paragraph_start(pos)
Get the starting position of a paragraph.
- Parameters:
- posint
Character position within paragraph.
- Return type:
- get_style(attribute, position=0)
Get an attribute style at the given position.
- Parameters:
- attributestr
Name of style attribute to query.
- positionint
Character position of document to query.
- Returns:
The style set for the attribute at the given position.
- get_style_range(attribute, start, end)
Get an attribute style over the given range.
If the style varies over the range, STYLE_INDETERMINATE is returned.
- Parameters:
- attributestr
Name of style attribute to query.
- startint
Starting character position.
- endint
Ending character position (exclusive).
- Returns:
The style set for the attribute over the given range, or STYLE_INDETERMINATE if more than one value is set.
- get_style_runs(attribute)
Get a style iterator over the given style attribute.
- Parameters:
- attributestr
Name of style attribute to query.
- Return type:
AbstractRunIterator
- insert_element(position, element, attributes=None)
Insert a element into the document.
See the
InlineElement
class documentation for details of usage.- Parameters:
- positionint
Character insertion point within document.
- element~pyglet.text.document.InlineElement
Element to insert.
- attributesdict
Optional dictionary giving named style attributes of the inserted text.
- insert_text(start, text, attributes=None)
Insert text into the document.
- Parameters:
- startint
Character insertion point within document.
- textstr
Text to insert.
- attributesdict
Optional dictionary giving named style attributes of the inserted text.
- on_delete_text(start, end)
Text was deleted from the document.
- Parameters:
- startint
Starting character position of deleted text.
- endint
Ending character position of deleted text (exclusive).
- Event:
- on_insert_text(start, text)
Text was inserted into the document.
- Parameters:
- startint
Character insertion point within document.
- textstr
The text that was inserted.
- Event:
- on_style_text(start, end, attributes)
Text character style was modified.
- Parameters:
- startint
Starting character position of modified text.
- endint
Ending character position of modified text (exclusive).
- attributesdict
Dictionary giving updated named style attributes of the text.
- Event:
- set_paragraph_style(start, end, attributes)
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).
- Parameters:
- startint
Starting character position.
- endint
Ending character position (exclusive).
- attributesdict
Dictionary giving named style attributes of the paragraphs.
- set_style(start, end, attributes)
Set text style of some or all of the document.
- Parameters:
- startint
Starting character position.
- endint
Ending character position (exclusive).
- attributesdict
Dictionary giving named style attributes of the text.
- event_types = ['on_insert_text', 'on_delete_text', 'on_style_text']
- property text
Document text.
For efficient incremental updates, use the
insert_text()
anddelete_text()
methods instead of replacing this property.- Type:
- class FormattedDocument(text='')
Simple implementation of a document that maintains text formatting.
Changes to text style are applied according to the description in
AbstractDocument
. All styles default toNone
.- get_element_runs()
- get_font(position, dpi=None)
Get the font instance used at the given position.
- See:
get_font_runs
- Parameters:
- positionint
Character position of document to query.
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
pyglet.font.Font
- Returns:
The font at the given position.
- get_font_runs(dpi=None)
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
,bold
anditalic
style attributes.- Parameters:
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
AbstractRunIterator
- get_style(attribute, position=0)
Get an attribute style at the given position.
- Parameters:
- attributestr
Name of style attribute to query.
- positionint
Character position of document to query.
- Returns:
The style set for the attribute at the given position.
- get_style_runs(attribute)
Get a style iterator over the given style attribute.
- Parameters:
- attributestr
Name of style attribute to query.
- Return type:
AbstractRunIterator
- class InlineElement(ascent, descent, advance)
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 a element (any of the advance, ascent, or descent instance 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.
- Ivariables:
- ascentint
Ascent of the element above the baseline, in pixels.
- descentint
Descent of the element below the baseline, in pixels. Typically negative.
- advanceint
Width of the element, in pixels.
- place(layout, x, y, z)
Construct an instance of the element at the given coordinates.
Called when the element’s position within a layout changes, either due to the initial condition, changes in the document or changes in the layout size.
It is the responsibility of the element to clip itself against the layout boundaries, and position itself appropriately with respect to the layout’s position and viewport offset.
The TextLayout.top_state graphics state implements this transform and clipping into window space.
- Parameters:
- layoutpyglet.text.layout.TextLayout
The layout the element moved within.
- xint
Position of the left edge of the element, relative to the left edge of the document, in pixels.
- yint
Position of the baseline, relative to the top edge of the document, in pixels. Note that this is typically negative.
- remove(layout)
Remove this element from a layout.
The counterpart of place; called when the element is no longer visible in the given layout.
- Parameters:
- layoutpyglet.text.layout.TextLayout
The layout the element was removed from.
- class UnformattedDocument(text='')
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.- get_element_runs()
- get_font(position=None, dpi=None)
Get the font instance used at the given position.
- See:
get_font_runs
- Parameters:
- positionint
Character position of document to query.
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
pyglet.font.Font
- Returns:
The font at the given position.
- get_font_runs(dpi=None)
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
,bold
anditalic
style attributes.- Parameters:
- dpifloat
Optional resolution to construct fonts at. See
pyglet.font.load()
.
- Return type:
AbstractRunIterator
- get_style(attribute, position=None)
Get an attribute style at the given position.
- Parameters:
- attributestr
Name of style attribute to query.
- positionint
Character position of document to query.
- Returns:
The style set for the attribute at the given position.
- get_style_runs(attribute)
Get a style iterator over the given style attribute.
- Parameters:
- attributestr
Name of style attribute to query.
- Return type:
AbstractRunIterator
- set_paragraph_style(start, end, attributes)
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).
- Parameters:
- startint
Starting character position.
- endint
Ending character position (exclusive).
- attributesdict
Dictionary giving named style attributes of the paragraphs.
- set_style(start, end, attributes)
Set text style of some or all of the document.
- Parameters:
- startint
Starting character position.
- endint
Ending character position (exclusive).
- attributesdict
Dictionary giving named style attributes of the text.
- STYLE_INDETERMINATE = 'indeterminate'
The style attribute takes on multiple values in the document.