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, 255))
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
- attributestr
Name of style attribute to retrieve. See pyglet.text.document for a list of recognised attribute names.
- Return type
- move_to_point(x, y)
Move the caret close to the given window coordinate.
The mark will be reset to
None.- Parameters
- xint
X coordinate.
- yint
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.
- on_translation_update()
- select_paragraph(x, y)
Select the paragraph at the given window coordinate.
- Parameters
- xint
X coordinate.
- yint
Y coordinate.
- select_to_point(x, y)
Move the caret close to the given window coordinate while maintaining the mark.
- Parameters
- xint
X coordinate.
- yint
Y coordinate.
- select_word(x, y)
Select the word at the given window coordinate.
- Parameters
- xint
X coordinate.
- yint
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
- attributesdict
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.
- property color
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__’scolorkeyword 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
- property 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
- property 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
Nonewhen there is no selection.- Type
- property position
Position of caret within document.