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)