# Module 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 documented, 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 a 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` 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.

Since: pyglet 1.1

## Classes

| InlineElement Arbitrary inline element positioned within a formatted document.
| AbstractDocument Abstract document interface used by all pyglet.text classes.
| UnformattedDocument A document having uniform style over all text.
| FormattedDocument Simple implementation of a document that maintains text formatting.

## Constants

| STYLE_INDETERMINATE = ``'``indeterminate``'`` The style attribute takes on multiple values in the document.