# Package pyglet.text

Text formatting, layout and display.

This module provides classes for loading styled documents from text files, HTML files and a pyglet-specific markup format. Documents can be styled with multiple fonts, colours, styles, text sizes, margins, paragraph alignments, and so on.

Using the layout classes, documents can be laid out on a single line or word-wrapped to fit a rectangle. A layout can then be efficiently drawn in a window or updated incrementally (for example, to support interactive text editing).

The label classes provide a simple interface for the common case where an application simply needs to display some text in a window.

A plain text label can be created with:

    label = pyglet.text.Label('Hello, world',
                              font_name='Times New Roman',
                              font_size=36,
                              x=10, y=10)

Alternatively, a styled text label using HTML can be created with:

    label = pyglet.text.HTMLLabel('<b>Hello</b>, <i>world</i>',
                                  x=10, y=10)

Either label can then be drawn at any time with:

    label.draw()

For details on the subset of HTML supported, see pyglet.text.formats.html.

Refer to the Programming Guide for advanced usage of the document and layout classes, including interactive editing, embedding objects within documents and creating scrollable layouts.

Since: pyglet 1.1

## Submodules

| pyglet.text.caret Provides keyboard and mouse editing procedures for text layout.
| pyglet.text.document Formatted and unformatted document interfaces used by text layout.
| pyglet.text.formats Document formats.
| pyglet.text.formats.attributed Extensible attributed text format for representing pyglet formatted documents.
| pyglet.text.formats.html Decode HTML into attributed text.
| pyglet.text.formats.plaintext Plain text decoder.
| pyglet.text.formats.structured Base class for structured (hierarchical) document formats.
| pyglet.text.layout Render simple text and formatted documents efficiently.
| pyglet.text.runlist Run list encoding utilities.

## Classes

| DocumentDecodeException An error occured decoding document text.
| DocumentDecoder Abstract document decoder.
| DocumentLabel Base label class.
| Label Plain text label.
| HTMLLabel HTML formatted text label.

## Functions

DocumentDecoder | get_decoder(filename, mimetype=None) Get a document decoder for the given filename and MIME type.
AbstractDocument | load(filename, file=None, mimetype=None) Load a document from a file.
FormattedDocument | decode_html(text, location=None) Create a document directly from some HTML formatted text.
FormattedDocument | decode_attributed(text) Create a document directly from some attributed text.
UnformattedDocument | decode_text(text) Create a document directly from some plain text.

## Function Details

### get_decoder

get_decoder(filename, mimetype=None)

Get a document decoder for the given filename and MIME type.

If `mimetype` is omitted it is guessed from the filename extension.

The following MIME types are supported:

`text/plain`
  Plain text
`text/html`
  HTML 4 Transitional
`text/vnd.pyglet-attributed`
  Attributed text; see pyglet.text.formats.attributed

DocumentDecodeException is raised if another MIME type is given.

Parameters:
  filename : str
    Filename to guess the MIME type from. If a MIME type is given, the filename is ignored.
  mimetype : str
    MIME type to lookup, or `None` to guess the type from the filename.
Returns: DocumentDecoder

### load

load(filename, file=None, mimetype=None)
Load a document from a file.

Parameters:
  filename : str
    Filename of document to load.
  file : file-like object
    File object containing encoded data. If omitted, `filename` is loaded from disk.
  mimetype : str
    MIME type of the document. If omitted, the filename extension is used to guess a MIME type. See get_decoder for a list of supported MIME types.
Returns: AbstractDocument

### decode_html

decode_html(text, location=None)
Create a document directly from some HTML formatted text.

Parameters:
  text : str
    HTML data to decode.
  location : str
    Location giving the base path for additional resources referenced from the document (e.g., images).
Returns: FormattedDocument

### decode_attributed

decode_attributed(text)

Create a document directly from some attributed text.

See pyglet.text.formats.attributed for a description of attributed text.

Parameters:
  text : str
    Attributed text to decode.
Returns: FormattedDocument

### decode_text

decode_text(text)
Create a document directly from some plain text.

Parameters:
  text : str
    Plain text to initialise the document with.
Returns: UnformattedDocument