# Class pyglet.text.layout.TextLayout

Known Subclasses:
  DocumentLabel, ScrollableTextLayout

Lay out and display documents.

This class is intended for displaying documents that do not change regularly -- any change will cost some time to lay out the complete document again and regenerate all vertex lists.

The benefit of this class is that texture state is shared between all layouts of this class. The time to draw one TextLayout may be roughly the same as the time to draw one IncrementalTextLayout; but drawing ten TextLayout objects in one batch is much faster than drawing ten incremental or scrollable text layouts.

Label and HTMLLabel provide a convenient interface to this class.

## Methods

| __init__(self, document, width=None, height=None, multiline=False, dpi=None, batch=None, group=None) Create a text layout.
| begin_update(self) Indicate that a number of changes to the layout or document are about to occur.
| end_update(self) Perform pending layout changes since begin_update.
| delete(self) Remove this layout from its batch.
| draw(self) Draw this text layout.
| on_insert_text(self, start, text) Event handler for `AbstractDocument.on_insert_text`.
| on_delete_text(self, start, end) Event handler for `AbstractDocument.on_delete_text`.
| on_style_text(self, start, end, attributes) Event handler for `AbstractDocument.on_style_text`.

## Properties

float | dpi Get DPI used by this layout.
| document
int | x X coordinate of the layout.
int | y Y coordinate of the layout.
int | width Width of the layout.
int | height Height of the layout.
bool | multiline Set if multiline layout is enabled.
str | anchor_x Horizontal anchor alignment.
str | anchor_y Vertical anchor alignment.
str | content_valign Vertical alignment of content within larger layout box.

## Instance Variables

Group | top_group = `<pyglet.text.layout.TextLayoutGroup object at 0x51`...`` Top-level rendering group.
Group | background_group = `OrderedGroup(0)` Rendering group for background color.
Group | foreground_group = `TextLayoutForegroundGroup(1)` Rendering group for glyphs.
Group | foreground_decoration_group = `TextLayoutForegroundDecorationGr`...`` Rendering group for glyph underlines.
int | content_height Calculuated height of the text in the layout.
int | content_width Calculuated width of the text in the layout.

## Method Details

### __init__

(Constructor) __init__(self, document, width=None, height=None, multiline=False, dpi=None, batch=None, group=None)
Create a text layout.

Parameters:
  document : AbstractDocument
    Document to display.
  width : int
    Width of the layout in pixels, or None
  height : int
    Height of the layout in pixels, or None
  multiline : bool
    If False, newline and paragraph characters are ignored, and text is not word-wrapped.
  dpi : float
    Font resolution; defaults to 96.
  batch : Batch
    Optional graphics batch to add this layout to.
  group : Group
    Optional rendering group to parent all groups this text layout uses. Note that layouts with different rendered simultaneously in a batch.

### begin_update

begin_update(self)

Indicate that a number of changes to the layout or document are about to occur.

Changes to the layout or document between calls to begin_update and end_update do not trigger any costly relayout of text. Relayout of all changes is performed when end_update is called.

Note that between the begin_update and end_update calls, values such as content_width and content_height are undefined (i.e., they may or may not be updated to reflect the latest changes).

### end_update

end_update(self)

Perform pending layout changes since begin_update.

See begin_update.

### draw

draw(self)

Draw this text layout.

Note that this method performs very badly if a batch was supplied to the constructor. If you add this layout to a batch, you should ideally use only the batch's draw method.

### on_insert_text

on_insert_text(self, start, text)

Event handler for `AbstractDocument.on_insert_text`.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

### on_delete_text

on_delete_text(self, start, end)

Event handler for `AbstractDocument.on_delete_text`.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

### on_style_text

on_style_text(self, start, end, attributes)

Event handler for `AbstractDocument.on_style_text`.

The event handler is bound by the text layout; there is no need for applications to interact with this method.

## Property Details

### dpi

Get DPI used by this layout.

Read-only.

Type:
  float

### document

### x

X coordinate of the layout.

See also anchor_x.

Type:
  int

### y

Y coordinate of the layout.

See also anchor_y.

Type:
  int

### width

Width of the layout.

This property has no effect if multiline is False.

Type:
  int

### height

Height of the layout.

Type:
  int

### multiline

Set if multiline layout is enabled.

If multiline is False, newline and paragraph characters are ignored and text is not word-wrapped.

Type:
  bool

### anchor_x

Horizontal anchor alignment.

This property determines the meaning of the x coordinate. It is one of the enumerants:

`"left"` (default)

  The X coordinate gives the position of the left edge of the layout.

`"center"`

  The X coordinate gives the position of the center of the layout.

`"right"`

  The X coordinate gives the position of the right edge of the layout.

For the purposes of calculating the position resulting from this alignment, the width of the layout is taken to be width if multiline is True, otherwise content_width.

Type:
  str

### anchor_y

Vertical anchor alignment.

This property determines the meaning of the y coordinate. It is one of the enumerants:

`"top"`

  The Y coordinate gives the position of the top edge of the layout.

`"center"`

  The Y coordinate gives the position of the center of the layout.

`"baseline"`

  The Y coordinate gives the position of the baseline of the first line of text in the layout.

`"bottom"` (default)

  The Y coordinate gives the position of the bottom edge of the layout.

For the purposes of calculating the position resulting from this alignment, the height of the layout is taken to be the smaller of height and content_height.

See also content_valign.

Type:
  str

### content_valign

Vertical alignment of content within larger layout box.

This property determines how content is positioned within the layout box when `content_height` is less than `height`. It is one of the enumerants:

`top` (default)
  Content is aligned to the top of the layout box.
`center`
  Content is centered vertically within the layout box.
`bottom`
  Content is aligned to the bottom of the layout box.

This property has no effect when `content_height` is greater than `height` (in which case the content is aligned to the top) or when `height` is `None` (in which case there is no vertical layout box dimension).

Type:
  str

## Instance Variable Details

### top_group

Top-level rendering group.

Type:
  Group
Value:

      TextLayoutGroup()

### foreground_decoration_group

Rendering group for glyph underlines.

Type:
  Group
Value:

      TextLayoutForegroundDecorationGroup(2)

### content_width

Calculuated width of the text in the layout. This may overflow the desired width if word-wrapping failed.

Type:
  int