Package com.intellij.openapi.editor

Interface Caret

All Superinterfaces:

Disposable, UserDataHolder, UserDataHolderEx

All Known Implementing Classes:

CaretImpl, InjectedCaret

public interface Caret
extends UserDataHolderEx, Disposable

Represents a specific caret instance in the editor. Provides methods to query and modify caret position and caret's associated selection.

Instances of this interface are supposed to be obtained from CaretModel instance, and not created explicitly.

Nested Class Summary

Nested classes/interfaces inherited from interface com.intellij.openapi.Disposable

Disposable.Parent

Method Summary

Modifier and Type	Method and Description
Caret	clone(boolean above) Clones the current caret and positions the new one right above or below the current one.
CaretModel	getCaretModel() Returns an instance of CaretModel, current caret is associated with.
Editor	getEditor() Returns an instance of Editor, current caret belongs to.
int	getLeadSelectionOffset() Returns the offset from which the user started to extend the selection (the selection start if the selection was extended in forward direction, or the selection end if it was extended backward).
VisualPosition	getLeadSelectionPosition()
LogicalPosition	getLogicalPosition() Returns the logical position of the caret.
int	getOffset() Returns the offset of the caret in the document.
java.lang.String	getSelectedText() Returns the text selected in the editor.
int	getSelectionEnd() Returns the end offset in the document of the selected text range, or the caret position if there is currently no selection.
VisualPosition	getSelectionEndPosition()
int	getSelectionStart() Returns the start offset in the document of the selected text range, or the caret position if there is currently no selection.
VisualPosition	getSelectionStartPosition()
CaretVisualAttributes	getVisualAttributes() Returns visual attributes currently set for the caret.
int	getVisualLineEnd()
int	getVisualLineStart()
VisualPosition	getVisualPosition() Returns the visual position of the caret.
boolean	hasSelection() Checks if a range of text is currently selected.
boolean	isAtBidiRunBoundary() Returns true if caret is located at a boundary between different runs of bidirectional text.
boolean	isAtRtlLocation() Returns true if caret is located in RTL text fragment.
boolean	isUpToDate() Caret position may be updated on document change (e.g.
boolean	isValid() Tells whether this caret is valid, i.e.
void	moveCaretRelatively(int columnShift, int lineShift, boolean withSelection, boolean scrollToCaret) Moves the caret by the specified number of lines and/or columns.
void	moveToLogicalPosition(LogicalPosition pos) Moves the caret to the specified logical position.
void	moveToOffset(int offset) Short hand for calling moveToOffset(int, boolean) with 'false' as a second argument.
void	moveToOffset(int offset, boolean locateBeforeSoftWrap) Moves the caret to the specified offset in the document.
void	moveToVisualPosition(VisualPosition pos) Moves the caret to the specified visual position.
void	removeSelection() Removes the selection in the editor.
void	selectLineAtCaret() Selects the entire line of text at the caret position.
void	selectWordAtCaret(boolean honorCamelWordsSettings) Selects the entire word at the caret position, optionally using camel-case rules to determine word boundaries.
void	setSelection(int startOffset, int endOffset) Selects the specified range of text.
void	setSelection(int startOffset, int endOffset, boolean updateSystemSelection) Selects the specified range of text.
void	setSelection(int startOffset, VisualPosition endPosition, int endOffset) Selects target range providing information about visual boundary of selection end.
void	setSelection(VisualPosition startPosition, int startOffset, VisualPosition endPosition, int endOffset) Selects target range based on its visual boundaries.
void	setSelection(VisualPosition startPosition, int startOffset, VisualPosition endPosition, int endOffset, boolean updateSystemSelection) Selects target range based on its visual boundaries.
void	setVisualAttributes(CaretVisualAttributes attributes) Sets caret's current visual attributes.

Methods inherited from interface com.intellij.openapi.util.UserDataHolderEx

putUserDataIfAbsent, replace

Methods inherited from interface com.intellij.openapi.util.UserDataHolder

getUserData, putUserData

Methods inherited from interface com.intellij.openapi.Disposable

dispose

Method Detail

getEditor

Editor getEditor()

Returns an instance of Editor, current caret belongs to.

getCaretModel

CaretModel getCaretModel()

Returns an instance of CaretModel, current caret is associated with.

isValid

boolean isValid()

Tells whether this caret is valid, i.e. recognized by the caret model currently. Caret is valid since its creation till its removal from caret model.

See Also:

CaretModel.addCaret(VisualPosition), CaretModel.removeCaret(Caret)

moveCaretRelatively

void moveCaretRelatively(int columnShift,
                         int lineShift,
                         boolean withSelection,
                         boolean scrollToCaret)

Moves the caret by the specified number of lines and/or columns.

Parameters:

columnShift - the number of columns to move the caret by.

lineShift - the number of lines to move the caret by.

withSelection - if true, the caret move should extend the selection in the document.

scrollToCaret - if true, the document should be scrolled so that the caret is visible after the move.

moveToLogicalPosition

void moveToLogicalPosition(LogicalPosition pos)

Moves the caret to the specified logical position. If corresponding position is in the folded region currently, the region will be expanded.

Parameters:

pos - the position to move to.

moveToVisualPosition

void moveToVisualPosition(VisualPosition pos)

Moves the caret to the specified visual position.

Parameters:

pos - the position to move to.

moveToOffset

void moveToOffset(int offset)

Short hand for calling moveToOffset(int, boolean) with 'false' as a second argument.

Parameters:

offset - the offset to move to

moveToOffset

void moveToOffset(int offset,
                  boolean locateBeforeSoftWrap)

Moves the caret to the specified offset in the document. If corresponding position is in the folded region currently, the region will be expanded.

Parameters:

offset - the offset to move to.

locateBeforeSoftWrap - there is a possible case that there is a soft wrap at the given offset, hence, the same offset corresponds to two different visual positions - just before soft wrap and just after soft wrap. We may want to clearly indicate where to put the caret then. Given parameter allows to do that. Note: it's ignored if there is no soft wrap at the given offset

isUpToDate

boolean isUpToDate()

Caret position may be updated on document change (e.g. consider that user updates from VCS that causes addition of text before caret. Caret offset, visual and logical positions should be updated then). So, there is a possible case that caret model in in the process of caret position update now.

Current method allows to check that.

Returns:

true if caret position is up-to-date for now; false otherwise

getLogicalPosition

LogicalPosition getLogicalPosition()

Returns the logical position of the caret.

Returns:

the caret position.

getVisualPosition

VisualPosition getVisualPosition()

Returns the visual position of the caret.

Returns:

the caret position.

getOffset

int getOffset()

Returns the offset of the caret in the document. Returns 0 for a disposed (invalid) caret.

Returns:

the caret offset.

See Also:

isValid()

getVisualLineStart

int getVisualLineStart()

Returns:

document offset for the start of the visual line where caret is located

getVisualLineEnd

int getVisualLineEnd()

Returns:

document offset that points to the first symbol shown at the next visual line after the one with caret on it

getSelectionStart

int getSelectionStart()

Returns the start offset in the document of the selected text range, or the caret position if there is currently no selection.

Returns:

the selection start offset.

getSelectionStartPosition

VisualPosition getSelectionStartPosition()

Returns:

object that encapsulates information about visual position of selected text start if any

getSelectionEnd

int getSelectionEnd()

Returns the end offset in the document of the selected text range, or the caret position if there is currently no selection.

Returns:

the selection end offset.

getSelectionEndPosition

VisualPosition getSelectionEndPosition()

Returns:

object that encapsulates information about visual position of selected text end if any;

getSelectedText

java.lang.String getSelectedText()

Returns the text selected in the editor.

Returns:

the selected text, or null if there is currently no selection.

getLeadSelectionOffset

int getLeadSelectionOffset()

Returns the offset from which the user started to extend the selection (the selection start if the selection was extended in forward direction, or the selection end if it was extended backward).

Returns:

the offset from which the selection was started, or the caret offset if there is currently no selection.

getLeadSelectionPosition

VisualPosition getLeadSelectionPosition()

Returns:

object that encapsulates information about visual position from which the user started to extend the selection if any

hasSelection

boolean hasSelection()

Checks if a range of text is currently selected.

Returns:

true if a range of text is selected, false otherwise.

setSelection

void setSelection(int startOffset,
                  int endOffset)

Selects the specified range of text.

System selection will be updated, if such feature is supported by current editor.

Parameters:

startOffset - the start offset of the text range to select.

endOffset - the end offset of the text range to select.

setSelection

void setSelection(int startOffset,
                  int endOffset,
                  boolean updateSystemSelection)

Selects the specified range of text.

Parameters:

startOffset - the start offset of the text range to select.

endOffset - the end offset of the text range to select.

updateSystemSelection - whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)

setSelection

void setSelection(int startOffset,
                  VisualPosition endPosition,
                  int endOffset)

Selects target range providing information about visual boundary of selection end.

That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.

Also, in column mode this method allows to create selection spanning virtual space after the line end.

System selection will be updated, if such feature is supported by current editor.

Parameters:

startOffset - start selection offset

endPosition - end visual position of the text range to select (null argument means that no specific visual position should be used)

endOffset - end selection offset

setSelection

void setSelection(VisualPosition startPosition,
                  int startOffset,
                  VisualPosition endPosition,
                  int endOffset)

Selects target range based on its visual boundaries.

That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.

Also, in column mode this method allows to create selection spanning virtual space after the line end.

System selection will be updated, if such feature is supported by current editor.

Parameters:

startPosition - start visual position of the text range to select (null argument means that no specific visual position should be used)

endPosition - end visual position of the text range to select (null argument means that no specific visual position should be used)

startOffset - start selection offset

endOffset - end selection offset

setSelection

void setSelection(VisualPosition startPosition,
                  int startOffset,
                  VisualPosition endPosition,
                  int endOffset,
                  boolean updateSystemSelection)

Selects target range based on its visual boundaries.

That is the case for soft wraps-aware processing where the whole soft wraps virtual space is matched to the same offset.

Also, in column mode this method allows to create selection spanning virtual space after the line end.

Parameters:

startPosition - start visual position of the text range to select (null argument means that no specific visual position should be used)

endPosition - end visual position of the text range to select (null argument means that no specific visual position should be used)

startOffset - start selection offset

endOffset - end selection offset

updateSystemSelection - whether system selection should be updated (might not have any effect if current editor doesn't support such a feature)

removeSelection

void removeSelection()

Removes the selection in the editor.

selectLineAtCaret

void selectLineAtCaret()

Selects the entire line of text at the caret position.

selectWordAtCaret

void selectWordAtCaret(boolean honorCamelWordsSettings)

Selects the entire word at the caret position, optionally using camel-case rules to determine word boundaries.

Parameters:

honorCamelWordsSettings - if true and "Use CamelHumps words" is enabled, upper-case letters within the word are considered as boundaries for the range of text to select.

clone

Caret clone(boolean above)

Clones the current caret and positions the new one right above or below the current one. If current caret has selection, corresponding selection will be set for the new caret.

Parameters:

above - if true, new caret will be created at the previous line, if false - on the next line

Returns:

newly created caret instance, or null if the caret cannot be created because it already exists at the new location or caret model doesn't support multiple carets.

isAtRtlLocation

boolean isAtRtlLocation()

Returns true if caret is located in RTL text fragment. In that case visual column number is inversely related to offset and logical column number in the vicinity of caret.

isAtBidiRunBoundary

boolean isAtBidiRunBoundary()

Returns true if caret is located at a boundary between different runs of bidirectional text. This means that text fragments at different sides of the boundary are non-adjacent in logical order. Caret can located at any side of the boundary, exact location can be determined from directionality flags of caret's logical and visual position (LogicalPosition.leansForward and VisualPosition.leansRight).

getVisualAttributes

CaretVisualAttributes getVisualAttributes()

Returns visual attributes currently set for the caret.

See Also:

setVisualAttributes(CaretVisualAttributes)

setVisualAttributes

void setVisualAttributes(CaretVisualAttributes attributes)

Sets caret's current visual attributes. This can have no effect if editor doesn't support changing caret's visual appearance.

See Also:

getVisualAttributes()