IncrementalTextLayout Class

Inheritance diagram of IncrementalTextLayout

class IncrementalTextLayout(document, width, height, multiline=False, dpi=None, batch=None, group=None, wrap_lines=True)

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.

Constructor:

__init__(document, width, height, multiline=False, dpi=None, batch=None, group=None, wrap_lines=True)

Methods:

begin_update() Indicate that a number of changes to the layout or document are about to occur.
delete()
dispatch_event(event_type, *args) Dispatch a single event to the attached handlers.
draw() Draw this text layout.
end_update() Perform pending layout changes since begin_update.
ensure_line_visible(line) Adjust view_y so that the line with the given index is visible.
ensure_x_visible(x) Adjust view_x so that the given X coordinate is visible.
event(*args) Function decorator for an event handler.
get_line_count() Get the number of lines in the text layout.
get_line_from_point(x, y) Get the closest line index to a point.
get_line_from_position(position) Get the line index of a character position in the document.
get_point_from_line(line) Get the X, Y coordinates of a line index.
get_point_from_position(position[, line]) Get the X, Y coordinates of a position in the document.
get_position_from_line(line) Get the first document character position of a given line index.
get_position_from_point(x, y) Get the closest document position to a point.
get_position_on_line(line, x) Get the closest document position for a given line index and X
on_delete_text(start, end)
on_insert_text(start, text)
on_style_text(start, end, attributes)
pop_handlers() Pop the top level of event handlers off the stack.
push_handlers(*args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers.
register_event_type(name) Register an event type with the dispatcher.
remove_handler(name, handler) Remove a single event handler.
remove_handlers(*args, **kwargs) Remove event handlers from the event stack.
set_handler(name, handler) Attach a single event handler.
set_handlers(*args, **kwargs) Attach one or more event handlers to the top level of the handler stack.
set_selection(start, end) Set the text selection range.

Events:

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

Attributes:

anchor_x
anchor_y
background_group A group with partial order.
content_valign Vertical alignment of content within larger layout box.
document
dpi Get DPI used by this layout.
event_types Type: list
foreground_decoration_group Rendering group for decorative elements (e.g., glyph underlines) in all text layouts.
foreground_group Rendering group for foreground elements (glyphs) in all text layouts.
height
multiline
selection_background_color Background color of active selection.
selection_color Text color of active selection.
selection_end End position of the active selection (exclusive).
selection_start Starting position of the active selection.
top_group Type: TextLayoutGroup
view_x Horizontal scroll offset.
view_y
width
x
y

Methods

IncrementalTextLayout.delete()
IncrementalTextLayout.ensure_line_visible(line)

Adjust view_y so that the line with the given index is visible.

Parameters:line (int) – Line index.
IncrementalTextLayout.ensure_x_visible(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
IncrementalTextLayout.get_line_count()

Get the number of lines in the text layout.

Return type:int
IncrementalTextLayout.get_line_from_point(x, y)

Get the closest line index to a point.

Parameters:
  • x (int) – X coordinate.
  • y (int) – Y coordinate.
Return type:

int

IncrementalTextLayout.get_line_from_position(position)

Get the line index of a character position in the document.

Parameters:position (int) – Document position.
Return type:int
IncrementalTextLayout.get_point_from_line(line)

Get the X, Y coordinates of a line index.

Parameters:line (int) – Line index.
Return type:(int, int)
Returns:(x, y)
IncrementalTextLayout.get_point_from_position(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.
Return type:

(int, int)

Returns:

(x, y)

IncrementalTextLayout.get_position_from_line(line)

Get the first document character position of a given line index.

Parameters:line (int) – Line index.
Return type:int
IncrementalTextLayout.get_position_from_point(x, y)

Get the closest document position to a point.

Parameters:
  • x (int) – X coordinate
  • y (int) – Y coordinate
IncrementalTextLayout.get_position_on_line(line, x)

Get the closest document position for a given line index and X coordinate.

Parameters:
  • line (int) – Line index.
  • x (int) – X coordinate.
Return type:

int

IncrementalTextLayout.on_delete_text(start, end)
IncrementalTextLayout.on_insert_text(start, text)
IncrementalTextLayout.on_style_text(start, end, attributes)
IncrementalTextLayout.set_selection(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.

Events

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

Attributes

IncrementalTextLayout.event_types = ['on_layout_update']
IncrementalTextLayout.height
IncrementalTextLayout.multiline
IncrementalTextLayout.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)
IncrementalTextLayout.selection_color

Text color of active selection.

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

Type:(int, int, int, int)
IncrementalTextLayout.selection_end

End position of the active selection (exclusive).

See:set_selection
Type:int
IncrementalTextLayout.selection_start

Starting position of the active selection.

See:set_selection
Type:int
IncrementalTextLayout.view_y
IncrementalTextLayout.width

Inherited members

Methods

IncrementalTextLayout.begin_update()

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

IncrementalTextLayout.dispatch_event(event_type, *args)

Dispatch a single event to the attached handlers.

The event is propagated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the dispatch_events method.

Since pyglet 1.2, the method returns EVENT_HANDLED if an event handler returned EVENT_HANDLED or EVENT_UNHANDLED if all events returned EVENT_UNHANDLED. If no matching event handlers are in the stack, False is returned.

Parameters:
  • event_type (str) – Name of the event.
  • args (sequence) – Arguments to pass to the event handler.
Return type:

bool or None

Returns:

(Since pyglet 1.2) EVENT_HANDLED if an event handler returned EVENT_HANDLED; EVENT_UNHANDLED if one or more event handlers were invoked but returned only EVENT_UNHANDLED; otherwise False. In pyglet 1.1 and earler, the return value is always None.

IncrementalTextLayout.draw()

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.

IncrementalTextLayout.end_update()

Perform pending layout changes since begin_update.

See begin_update.

IncrementalTextLayout.event(*args)

Function decorator for an event handler.

Usage:

win = window.Window()

@win.event
def on_resize(self, width, height):
    # ...

or:

@win.event('on_resize')
def foo(self, width, height):
    # ...
IncrementalTextLayout.pop_handlers()

Pop the top level of event handlers off the stack.

IncrementalTextLayout.push_handlers(*args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable’s __name__ attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

classmethod IncrementalTextLayout.register_event_type(name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters:name (str) – Name of the event to register.
IncrementalTextLayout.remove_handler(name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers; and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters:
  • name (str) – Name of the event type to remove.
  • handler (callable) – Event handler to remove.
IncrementalTextLayout.remove_handlers(*args, **kwargs)

Remove event handlers from the event stack.

See push_handlers for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers and pop_handlers.

IncrementalTextLayout.set_handler(name, handler)

Attach a single event handler.

Parameters:
  • name (str) – Name of the event type to attach to.
  • handler (callable) – Event handler to attach.
IncrementalTextLayout.set_handlers(*args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers for the accepted argument types.

Attributes

IncrementalTextLayout.anchor_x
IncrementalTextLayout.anchor_y
IncrementalTextLayout.background_group = OrderedGroup(0)
IncrementalTextLayout.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
IncrementalTextLayout.document
IncrementalTextLayout.dpi

Get DPI used by this layout.

Read-only.

Type:float
IncrementalTextLayout.foreground_decoration_group = TextLayoutForegroundDecorationGroup(2)
IncrementalTextLayout.foreground_group = TextLayoutForegroundGroup(1)
IncrementalTextLayout.top_group = <pyglet.text.layout.TextLayoutGroup object at 0x96bbd2c>
IncrementalTextLayout.view_x

Horizontal scroll offset.

The initial value is 0, and the left edge of the text will touch the left side of the layout bounds. A positive value causes the text to “scroll” to the right. Values are automatically clipped into the range [0, content_width - width]

Type:int
IncrementalTextLayout.x
IncrementalTextLayout.y

Table Of Contents

Previous topic

TextLayoutTextureGroup Class

Next topic

ScrollableTextLayout Class