Caret

The SyntaxEditor caret is the bar that blinks within an editor view and marks the location where typing will insert text. It also is linked to the end position of a selection. SyntaxEditor optionally supports multiple selections and therefore multiple carets, which enables simultaneous editing in several document locations at the same time.

Accessing the Caret

The primary selection's caret and its functionality described below is available via the IEditorViewSelection interface, which can be retrieved from the SyntaxEditor.ActiveView.Selection property.

Determining and Moving the Caret Location

The primary selection has several properties for determining its caret location. A couple of the properties can be set to move the caret.

This code moves the caret to the start of the third line (the value is zero-based):

editor.ActiveView.Selection.CaretPosition = new TextPosition(2, 0);

Text positions are zero-based by default. Use the one-based TextPosition.DisplayLine and DisplayCharacter properties when displaying the position in a status bar or other user interface.

Multiple Selections and Carets

A caret appears at the end of each editor view selection. Multiple selections are supported when the SyntaxEditor.AreMultipleSelectionRangesEnabled property is true.

See the Selection topic for more information on working with multiple selections and how end users can add selections at run-time.

Changing the Blink Interval

The caret blink interval is set by default to 500ms.

Use the SyntaxEditor.CaretBlinkInterval property to change the blink interval to be faster or slower. The value indicates the millisecond delay between blinks.

This code changes the blink interval to one second:

editor.CaretBlinkInterval = 1000;

Changing the Insert and Overwrite Mode Width/Style

The caret can be in one of two modes: insert and overwrite. Insert mode is the traditional mode where typed text is inserted directly at the caret's offset. Overwrite mode will insert text at the caret's offset but will first remove any existing character on the line that is already at that offset.

The SyntaxEditor.CaretInsertWidth and CaretOverwriteWidth properties can be used to tweak the width of the caret in each respective mode.

The CaretInsertKind and CaretOverwriteKind properties accept a CaretKind value. This value determines the shape/alignment of the caret and can be VerticalLine, HorizontalUnderline, or Block.

High-Contrast Inversion

The caret normally renders in a single color that contrasts with the editor's background. The SyntaxEditor.UseInvertedCaret property can be set to true, which causes the caret to invert everything behind it. This inversion is high-contrast and its appearance was commonly used in classic code editors.

Temporarily Suspending Blinking

The SyntaxEditor.SuspendCaretBlinking method can be used to temporarily suspend blinking of the caret. It accepts a boolean parameter indicating whether to display the caret while suspended or not. Generally, false is passed to this method.

When the caret should resume blinking, call the ResumeCaretBlinking method.

Caret Move Event

The SyntaxEditor.ViewSelectionChanged event is raised whenever the caret moves, since the caret is always in sync with the end of the selection.

See the Selection topic for more information on this event.

Scroll to Caret

The editor view will auto-scroll by default to the primary caret when the selection is changed. A batch can be created on the selection using a NoScrollToCaret option to prevent auto-scrolling to the caret following text changes:

using (var batch = editor.ActiveView.Selection.CreateBatch(EditorViewSelectionBatchOptions.NoScrollToCaret)) {
	// Perform text changes here
}

The SyntaxEditor.ScrollToCaretOnSelectAll property that determines whether to scroll to the caret when a select all operation is performed. It defaults to true.

The IEditorViewScroller interface defines a ScrollToCaret method that can be called manually to scroll to the caret. This code scrolls the active view to the caret:

editor.ActiveView.Scroller.ScrollToCaret();