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)

New in version 1.1.

class Caret(layout, batch=None, color=(0, 0, 0))

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.

delete()

Remove the caret from its batch.

Also disconnects the caret from further layout events.

get_style(attribute)

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 pyglet.text.document for a list of recognised attribute names.

Return type:

object

move_to_point(x, y)

Move the caret close to the given window coordinate.

The mark will be reset to None.

Parameters:

x : int

X coordinate.

y : int

Y coordinate.

on_activate()

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

The caret is hidden when the window is not active.

on_deactivate()

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

The caret is hidden when the window is not active.

on_layout_update()

Handler for the IncrementalTextLayout.on_layout_update event.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

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.

on_mouse_press(x, y, button, modifiers)

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.

on_mouse_scroll(x, y, scroll_x, scroll_y)

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

on_text(text)

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.

on_text_motion(motion, select=False)

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.

on_text_motion_select(motion)

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.

select_paragraph(x, y)

Select the paragraph at the given window coordinate.

Parameters:

x : int

X coordinate.

y : int

Y coordinate.

select_to_point(x, y)

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

Parameters:

x : int

X coordinate.

y : int

Y coordinate.

select_word(x, y)

Select the word at the given window coordinate.

Parameters:

x : int

X coordinate.

y : int

Y coordinate.

set_style(attributes)

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

Dict mapping attribute names to style values. See pyglet.text.document for a list of recognised attribute names.

PERIOD = 0.5

Blink period, in seconds.

SCROLL_INCREMENT = 16

Pixels to scroll viewport per mouse scroll wheel movement. Defaults to 12pt at 96dpi.

color

Caret color.

The default caret color is [0, 0, 0] (black). Each RGB color component is in the range 0 to 255.

Type:(int, int, int)

line

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.

Return type:int

mark

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.

Type:int

position

Position of caret within document.

visible

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.

Type:bool