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()
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
Calculuated height of the text in the layout.
(Inherited from pyglet.text.layout.TextLayout)
int content_width
Calculuated 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 0x53...
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()

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)