pyglet.text.caret

Provides keyboard and mouse editing procedures for text layout.

Example usage:

from pyglet import window
from pyglet.text import layout, caret

my_window = window.Window(...)
my_layout = layout.IncrementalTextLayout(...)
my_caret = caret.Caret(my_layout)
my_window.push_handlers(my_caret)

class Caret

Visible text insertion marker for pyglet.text.layout.IncrementalTextLayout.

The caret is drawn as a single vertical bar at the document position on a text layout object. If mark is not None, it gives the unmoving end of the current text selection. The visible text selection on the layout is updated along with mark and position.

By default, the layout’s graphics batch is used, so the caret does not need to be drawn explicitly. Even if a different graphics batch is supplied, the caret will be correctly positioned and clipped within the layout.

Updates to the document (and so the layout) are automatically propagated to the caret.

If the window argument is supplied, the caret object dispatches the on_clipboard_copy event when copying text and copies the text. Pasting also works, which will dispatch the on_clipboard_paste event, and pastes the text to the current position of the caret, overriding selection.

The caret object can be pushed onto a window event handler stack with Window.push_handlers. The caret will respond correctly to keyboard, text, mouse and activation events, including double- and triple-clicks. If the text layout is being used alongside other graphical widgets, a GUI toolkit will be needed to delegate keyboard and mouse events to the appropriate widget. Pyglet does not provide such a toolkit at this stage.

PERIOD: float = 0.5: Blink period, in seconds.

SCROLL_INCREMENT: int = 16: Pixels to scroll viewport per mouse scroll wheel movement. Defaults to 12pt at 96dpi.

property color: tuple[int, int, int, int]

An RGBA tuple of the current caret color.

When blinking off, the alpha channel will be set to 0. The default caret color when visible is (0, 0, 0, 255) (opaque black).

You may set the color to an RGBA or RGB color tuple.

Warning

This setter can fail for a short time after layout / window init!

Use __init__’s color keyword argument instead if you run into this problem.

Each color channel must be between 0 and 255, inclusive. If the color set to an RGB color, the previous alpha channel value will be used.

event_types: list = ['on_clipboard_copy', 'on_clipboard_paste']

property layout: IncrementalTextLayout

property line: int

Index of line containing the caret’s position.

When set, position is modified to place the caret on requested line while maintaining the closest possible X offset.

property mark: int

Position of immovable end of text selection within document.

An interactive text selection is determined by its immovable end (the caret’s position when a mouse drag begins) and the caret’s position, which moves interactively by mouse and keyboard input.

This property is None when there is no selection.

property position: int: Position of caret within document.

property visible: bool

Caret visibility.

The caret may be hidden despite this property due to the periodic blinking or by on_deactivate if the event handler is attached to a window.