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.

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.

__init__( layout: IncrementalTextLayout, batch: Batch = None, color: tuple[int, int, int, int] = (0, 0, 0, 255), ) → None

Create a caret for a layout.

By default the layout’s batch is used, so the caret does not need to be drawn explicitly.

Parameters:

layout~pyglet.text.layout.IncrementalTextLayout: Layout to control.
batch~pyglet.graphics.Batch: Graphics batch to add vertices to.
color(int, int, int, int): An RGBA or RGB tuple with components in the range [0, 255]. RGB colors will be treated as having an opacity of 255.

delete() → None

Remove the caret from its batch.

Also disconnects the caret from further layout events.

Return type:: None

get_style(attribute: str) → Any

Get the document’s named style at the caret’s current position.

If there is a text selection and the style varies over the selection, pyglet.text.document.STYLE_INDETERMINATE is returned.

Parameters:: attribute (str) – Name of style attribute to retrieve. See document for a list of recognised attribute names.
Return type:: Any

move_to_point(x: int, y: int) → None

Move the caret close to the given window coordinate.

The mark will be reset to None.

Return type:: None

on_activate() → bool

Handler for the pyglet.window.Window.on_activate event.

The caret is hidden when the window is not active.

Return type:: bool

on_deactivate() → bool

Handler for the pyglet.window.Window.on_deactivate event.

The caret is hidden when the window is not active.

Return type:: bool

on_layout_update() → None

Handler for the IncrementalTextLayout.on_layout_update event.

Return type:: None

on_mouse_drag( x: int, y: int, dx: int, dy: int, buttons: int, modifiers: int, ) → bool

Handler for the pyglet.window.Window.on_mouse_drag event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

Return type:: bool

on_mouse_press(x: int, y: int, button: int, modifiers: int) → bool

Handler for the pyglet.window.Window.on_mouse_press event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

This handler keeps track of the number of mouse presses within a short span of time and uses this to reconstruct double- and triple-click events for selecting words and paragraphs. This technique is not suitable when a GUI toolkit is in use, as the active widget must also be tracked. Do not use this mouse handler if a GUI toolkit is being used.

Return type:: bool

on_mouse_scroll(x: float, y: float, scroll_x: float, scroll_y: float) → bool

Handler for the pyglet.window.Window.on_mouse_scroll event.

Mouse handlers do not check the bounds of the coordinates: GUI toolkits should filter events that do not intersect the layout before invoking this handler.

The layout viewport is scrolled by SCROLL_INCREMENT pixels per “click”.

Return type:: bool

on_text(text: str) → bool

Handler for the pyglet.window.Window.on_text event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_text_motion(motion: int, select: bool = False) → bool

Handler for the pyglet.window.Window.on_text_motion event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_text_motion_select(motion: int) → bool

Handler for the pyglet.window.Window.on_text_motion_select event.

Caret keyboard handlers assume the layout always has keyboard focus. GUI toolkits should filter keyboard and text events by widget focus before invoking this handler.

Return type:: bool

on_translation_update() → None

Return type:: None

select_all() → None

Select all text in the document.

Return type:: None

select_paragraph(x: int, y: int) → None

Select the paragraph at the given window coordinate.

Return type:: None

select_to_point(x: int, y: int) → None

Move the caret close to the given window coordinate while maintaining the mark.

Return type:: None

select_word(x: int, y: int) → None

Select the word at the given window coordinate.

Return type:: None

set_style(attributes: dict[str, Any]) → None

Set the document style at the caret’s current position.

If there is a text selection the style is modified immediately. Otherwise, the next text that is entered before the position is modified will take on the given style.

Parameters:: attributes (dict[str, Any]) – Dict mapping attribute names to style values. See document for a list of recognised attribute names.
Return type:: None

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.

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.