# Class pyglet.text.caret.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 propogated 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.

## Methods

| __init__(self, layout, batch=None, color=`(`0`,` 0`,` 0`)`) Create a caret for a layout.
| delete(self) Remove the caret from its batch.
object | get_style(self, attribute) Get the document's named style at the caret's current position.
| set_style(self, attributes) Set the document style at the caret's current position.
| move_to_point(self, x, y) Move the caret close to the given window coordinate.
| select_to_point(self, x, y) Move the caret close to the given window coordinate while maintaining the mark.
| select_word(self, x, y) Select the word at the given window coordinate.
| select_paragraph(self, x, y) Select the paragraph at the given window coordinate.
| on_layout_update(self)
| on_text(self, text) Handler for the pyglet.window.Window.on_text event.
| on_text_motion(self, motion, select=False) Handler for the pyglet.window.Window.on_text_motion event.
| on_text_motion_select(self, motion) Handler for the pyglet.window.Window.on_text_motion_select event.
| on_mouse_scroll(self, x, y, scroll_x, scroll_y) Handler for the pyglet.window.Window.on_mouse_scroll event.
| on_mouse_press(self, x, y, button, modifiers) Handler for the pyglet.window.Window.on_mouse_press event.
| on_mouse_drag(self, x, y, dx, dy, buttons, modifiers) Handler for the pyglet.window.Window.on_mouse_drag event.
| on_activate(self) Handler for the pyglet.window.Window.on_activate event.
| on_deactivate(self) Handler for the pyglet.window.Window.on_deactivate event.

## Properties

bool | visible Caret visibility.
(int, int, int) | color Caret color.
int | position Position of caret within document.
int | mark Position of immovable end of text selection within document.
int | line Index of line containing the caret's position.

## Constants

| PERIOD = `0.5` Blink period, in seconds.
| SCROLL_INCREMENT = `16` Pixels to scroll viewport per mouse scroll wheel movement.

## Method Details

### __init__

(Constructor) __init__(self, layout, batch=None, color=`(`0`,` 0`,` 0`)`)

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 : TextLayout
    Layout to control.
  batch : Batch
    Graphics batch to add vertices to.
  color : (int, int, int)
    RGB tuple with components in range [0, 255].

### delete

delete(self)

Remove the caret from its batch.

Also disconnects the caret from further layout events.

### get_style

get_style(self, 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.
Returns: object

### set_style

set_style(self, 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.

### move_to_point

move_to_point(self, 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.

### select_to_point

select_to_point(self, 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

select_word(self, x, y)
Select the word at the given window coordinate.

Parameters:
  x : int
    X coordinate.
  y : int
    Y coordinate.

### select_paragraph

select_paragraph(self, x, y)
Select the paragraph at the given window coordinate.

Parameters:
  x : int
    X coordinate.
  y : int
    Y coordinate.

### on_text

on_text(self, 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

on_text_motion(self, 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

on_text_motion_select(self, 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_mouse_scroll

on_mouse_scroll(self, 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_mouse_press

on_mouse_press(self, 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_drag

on_mouse_drag(self, 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_activate

on_activate(self)

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

The caret is hidden when the window is not active.

### on_deactivate

on_deactivate(self)

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

The caret is hidden when the window is not active.

## Property Details

### 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

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

### position

Position of caret within document.

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

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

Type:
  int

## Constant Details

### SCROLL_INCREMENT

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

Value:

      16