# Class pyglet.text.layout.IncrementalTextLayout

           TextLayout --+
                        |
     ScrollableTextLayout --+
                            |
    event.EventDispatcher --+
                            |
                           IncrementalTextLayout

Displayed text suitable for interactive editing and/or scrolling large documents.

Unlike TextLayout and ScrollableTextLayout, this class generates vertex lists only for lines of text that are visible. As the document is scrolled, vertex lists are deleted and created as appropriate to keep video memory usage to a minimum and improve rendering speed.

Changes to the document are quickly reflected in this layout, as only the affected line(s) are reflowed. Use begin_update and end_update to further reduce the amount of processing required.

The layout can also display a text selection (text with a different background color). The Caret class implements a visible text cursor and provides event handlers for scrolling, selecting and editing text in an incremental text layout.

## Events

| on_layout_update(self) Some or all of the layout text was reflowed.

## Methods

| __init__(self, document, width, height, multiline=False, dpi=None, batch=None, group=None)
| delete(self) Remove this layout from its batch.
| 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`.
| set_selection(self, start, end) Set the text selection range.
| get_position_from_point(self, x, y) Get the closest document position to a point.
(int, int) | get_point_from_position(self, position, line=None) Get the X, Y coordinates of a position in the document.
int | get_line_from_point(self, x, y) Get the closest line index to a point.
(int, int) | get_point_from_line(self, line) Get the X, Y coordinates of a line index.
int | get_line_from_position(self, position) Get the line index of a character position in the document.
int | get_position_from_line(self, line) Get the first document character position of a given line index.
int | get_position_on_line(self, line, x) Get the closest document position for a given line index and X coordinate.
int | get_line_count(self) Get the number of lines in the text layout.
| ensure_line_visible(self, line) Adjust view_y so that the line with the given index is visible.
| ensure_x_visible(self, x) Adjust view_x so that the given X coordinate is visible.
| begin_update(self) Indicate that a number of changes to the layout or document are about to occur. (Inherited from pyglet.text.layout.TextLayout)
| dispatch_event(self, event_type, *args) Dispatch a single event to the attached handlers. (Inherited from pyglet.event.EventDispatcher)
| draw(self) Draw this text layout. (Inherited from pyglet.text.layout.TextLayout)
| end_update(self) Perform pending layout changes since begin_update. (Inherited from pyglet.text.layout.TextLayout)
| event(self, *args) Function decorator for an event handler. (Inherited from pyglet.event.EventDispatcher)
| pop_handlers(self) Pop the top level of event handlers off the stack. (Inherited from pyglet.event.EventDispatcher)
| push_handlers(self, *args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers. (Inherited from pyglet.event.EventDispatcher)
| register_event_type(cls, name) Register an event type with the dispatcher. (Inherited from pyglet.event.EventDispatcher)
| remove_handler(self, name, handler) Remove a single event handler. (Inherited from pyglet.event.EventDispatcher)
| remove_handlers(self, *args, **kwargs) Remove event handlers from the event stack. (Inherited from pyglet.event.EventDispatcher)
| set_handler(self, name, handler) Attach a single event handler. (Inherited from pyglet.event.EventDispatcher)
| set_handlers(self, *args, **kwargs) Attach one or more event handlers to the top level of the handler stack. (Inherited from pyglet.event.EventDispatcher)

## Properties

| width
| height
bool | multiline Set if multiline layout is enabled.
int | view_y Vertical scroll offset.
int | selection_start Starting position of the active selection.
int | selection_end End position of the active selection (exclusive).
(int, int, int, int) | selection_color Text color of active selection.
(int, int, int, int) | selection_background_color Background color of active selection.
str | anchor_x Horizontal anchor alignment. (Inherited from pyglet.text.layout.ScrollableTextLayout)
str | anchor_y Vertical anchor alignment. (Inherited from pyglet.text.layout.ScrollableTextLayout)
str | content_valign Vertical alignment of content within larger layout box. (Inherited from pyglet.text.layout.TextLayout)
| document (Inherited from pyglet.text.layout.TextLayout)
float | dpi Get DPI used by this layout. (Inherited from pyglet.text.layout.TextLayout)
int | view_x Horizontal scroll offset. (Inherited from pyglet.text.layout.ScrollableTextLayout)
int | x X coordinate of the layout. (Inherited from pyglet.text.layout.ScrollableTextLayout)
int | y Y coordinate of the layout. (Inherited from pyglet.text.layout.ScrollableTextLayout)

## Instance Variables

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

## Class Variables

| event_types = ``[``'``on_layout_update``'``]``

## Event Details

### on_layout_update

on_layout_update(self)

Some or all of the layout text was reflowed.

Text reflow is caused by document edits or changes to the layout's size. Changes to the layout's position or active selection, and certain document edits such as text color, do not cause a reflow.

Handle this event to update the position of a graphical element that depends on the laid out position of a glyph or line.

## Method Details

### __init__

(Constructor) __init__(self, document, width, height, multiline=False, dpi=None, batch=None, group=None)

Overrides:
  ScrollableTextLayout.__init__

### delete

delete(self)
Remove this layout from its batch.

Overrides:
  TextLayout.delete

### 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.

Overrides:
  TextLayout.on_insert_text

### 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.

Overrides:
  TextLayout.on_delete_text

### 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.

Overrides:
  TextLayout.on_style_text

### set_selection

set_selection(self, start, end)

Set the text selection range.

If `start` equals `end` no selection will be visible.

Parameters:
  start : int
    Starting character position of selection.
  end : int
    End of selection, exclusive.

### get_position_from_point

get_position_from_point(self, x, y)
Get the closest document position to a point.

Parameters:
  x : int
    X coordinate
  y : int
    Y coordinate

### get_point_from_position

get_point_from_position(self, position, line=None)

Get the X, Y coordinates of a position in the document.

The position that ends a line has an ambiguous point: it can be either the end of the line, or the beginning of the next line. You may optionally specify a line index to disambiguate the case.

The resulting Y coordinate gives the baseline of the line.

Parameters:
  position : int
    Character position within document.
  line : int
    Line index.
Returns:
  (int, int): (x, y)

### get_line_from_point

get_line_from_point(self, x, y)
Get the closest line index to a point.

Parameters:
  x : int
    X coordinate.
  y : int
    Y coordinate.
Returns: int

### get_point_from_line

get_point_from_line(self, line)
Get the X, Y coordinates of a line index.

Parameters:
  line : int
    Line index.
Returns:
  (int, int): (x, y)

### get_line_from_position

get_line_from_position(self, position)
Get the line index of a character position in the document.

Parameters:
  position : int
    Document position.
Returns: int

### get_position_from_line

get_position_from_line(self, line)
Get the first document character position of a given line index.

Parameters:
  line : int
    Line index.
Returns: int

### get_position_on_line

get_position_on_line(self, line, x)
Get the closest document position for a given line index and X coordinate.

Parameters:
  line : int
    Line index.
  x : int
    X coordinate.
Returns: int

### ensure_line_visible

ensure_line_visible(self, line)
Adjust view_y so that the line with the given index is visible.

Parameters:
  line : int
    Line index.

### ensure_x_visible

ensure_x_visible(self, x)

Adjust view_x so that the given X coordinate is visible.

The X coordinate is given relative to the current view_x.

Parameters:
  x : int
    X coordinate

## Property Details

### width

### height

### 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

### view_y

Vertical scroll offset.

The initial value is 0, and the top of the text will touch the top of the layout bounds (unless the content height is less than the layout height, in which case content_valign is used).

A negative value causes the text to "scroll" upwards. Values outside of the range `[height - content_height, 0]` are automatically clipped in range.

Type:
  int

### selection_start

Starting position of the active selection.

See Also: set_selection

Type:
  int

### selection_end

End position of the active selection (exclusive).

See Also: set_selection

Type:
  int

### selection_color

Text color of active selection.

The color is an RGBA tuple with components in range [0, 255].

Type:
  (int, int, int, int)

### selection_background_color

Background color of active selection.

The color is an RGBA tuple with components in range [0, 255].

Type:
  (int, int, int, int)