CaretModel (Unofficial IntelliJ Community Edition API docs)

All Known Implementing Classes:

CaretModelImpl
```
public interface CaretModel
```
Provides services for moving the caret and retrieving information about caret position. May support several carets existing simultaneously in a document. supportsMultipleCarets() method can be used to find out whether particular instance of CaretModel does it. If it does, query and update methods for caret position operate on a certain 'primary' caret. There exists a way to perform the same operation(s) on each caret - see runForEachCaret(CaretAction) method. Within its context, query and update methods operate on the current caret in that iteration. This behaviour can change in future though, so using caret and selection query and update methods in actions that need to operate on multiple carets is discouraged - methods on Caret instances obtained via getAllCarets() or runForEachCaret(CaretAction) should be used instead.
How 'primary' caret is determined by the model is not defined (currently it's the most recently added caret, but that can change).
At all times at least one caret will exist in a document.
Update methods, runBatchCaretOperation(Runnable) and runForEachCaret(CaretAction) methods should only be run from EDT. Query methods can be run from any thread, when called not from EDT, those methods are 'not aware' of 'runForEachCaret' scope - they will always return information about primary caret.

See Also:

Editor.getCaretModel()

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`Caret`	`addCaret(LogicalPosition pos, boolean makePrimary)` Adds a new caret at the given position, and returns corresponding `Caret` instance.
`default Caret`	`addCaret(VisualPosition pos)` Same as `addCaret(VisualPosition, boolean)` with `true` as a `makePrimary` boolean parameter value.
`Caret`	`addCaret(VisualPosition pos, boolean makePrimary)` Adds a new caret at the given position, and returns corresponding `Caret` instance.
`void`	`addCaretActionListener(CaretActionListener listener, Disposable disposable)` Adds a listener which will be notified before and after all-caret operations are performed by `runForEachCaret(CaretAction)` and `runForEachCaret(CaretAction, boolean)`.
`void`	`addCaretListener(CaretListener listener)` Adds a listener for receiving notifications about caret movement and caret addition/removal
`default void`	`addCaretListener(CaretListener listener, Disposable parentDisposable)` Adds a listener for receiving notifications about caret movement and caret addition/removal.
`java.util.List<Caret>`	`getAllCarets()` Returns all carets currently existing in the document, ordered by their visual position in editor.
`Caret`	`getCaretAt(VisualPosition pos)` Returns a caret at the given position in the document, or `null`, if there's no caret there.
`int`	`getCaretCount()` Returns number of carets currently existing in the document
`java.util.List<CaretState>`	`getCaretsAndSelections()` Returns the current positions of all carets and their selections.
`Caret`	`getCurrentCaret()` Returns current caret - the one, query and update methods in the model operate at the moment.
`default LogicalPosition`	`getLogicalPosition()` Returns the logical position of the caret.
`default int`	`getOffset()` Returns the offset of the caret in the document.
`Caret`	`getPrimaryCaret()` Returns the 'primary' caret.
`TextAttributes`	`getTextAttributes()` Returns visual representation of caret (e.g.
`default int`	`getVisualLineEnd()`
`default int`	`getVisualLineStart()`
`default VisualPosition`	`getVisualPosition()` Returns the visual position of the caret.
`default boolean`	`isUpToDate()` Caret position may be updated on document change (e.g.
`default void`	`moveCaretRelatively(int columnShift, int lineShift, boolean withSelection, boolean blockSelection, boolean scrollToCaret)` Moves the caret by the specified number of lines and/or columns.
`default void`	`moveToLogicalPosition(LogicalPosition pos)` Moves the caret to the specified logical position.
`default void`	`moveToOffset(int offset)` Short hand for calling `moveToOffset(int, boolean)` with `'false'` as a second argument.
`default void`	`moveToOffset(int offset, boolean locateBeforeSoftWrap)` Moves the caret to the specified offset in the document.
`default void`	`moveToVisualPosition(VisualPosition pos)` Moves the caret to the specified visual position.
`boolean`	`removeCaret(Caret caret)` Removes a given caret if it's recognized by the model and is not the only existing caret in the document, returning `true`.
`void`	`removeCaretListener(CaretListener listener)` Removes a listener for receiving notifications about caret movement and caret addition/removal
`void`	`removeSecondaryCarets()` Removes all carets except the 'primary' one from the document.
`void`	`runBatchCaretOperation(java.lang.Runnable runnable)` Executes the given task, performing caret merging afterwards.
`void`	`runForEachCaret(CaretAction action)` Same as `runForEachCaret(CaretAction, boolean)` with `reverseOrder` set to `false`
`void`	`runForEachCaret(CaretAction action, boolean reverseOrder)` Executes the given task for each existing caret.
`void`	`setCaretsAndSelections(java.util.List<? extends CaretState> caretStates)` Sets the number of carets, their positions and selection ranges according to the provided data.
`void`	`setCaretsAndSelections(java.util.List<? extends CaretState> caretStates, boolean updateSystemSelection)` Sets the number of carets, their positions and selection ranges according to the provided data.
`boolean`	`supportsMultipleCarets()` Tells whether multiple coexisting carets are supported by this CaretModel instance.

- Method Detail
  - moveCaretRelatively
```
default void moveCaretRelatively(int columnShift,
                                 int lineShift,
                                 boolean withSelection,
                                 boolean blockSelection,
                                 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 range in the document.
    
    blockSelection - This parameter is currently ignored.
    
    scrollToCaret - if true, the document should be scrolled so that the caret is visible after the move.
  - moveToLogicalPosition
```
default 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
```
default void moveToVisualPosition(VisualPosition pos)
```
    Moves the caret to the specified visual position.
    
    Parameters:
    
    pos - the position to move to.
  - moveToOffset
```
default 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
```
default 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
```
default 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
```
default LogicalPosition getLogicalPosition()
```
    Returns the logical position of the caret.
    
    Returns:
    
    the caret position.
  - getVisualPosition
```
default VisualPosition getVisualPosition()
```
    Returns the visual position of the caret.
    
    Returns:
    
    the caret position.
  - getOffset
```
default int getOffset()
```
    Returns the offset of the caret in the document.
    
    Returns:
    
    the caret offset.
  - addCaretListener
```
void addCaretListener(CaretListener listener)
```
    Adds a listener for receiving notifications about caret movement and caret addition/removal
    
    Parameters:
    
    listener - the listener instance.
  - addCaretListener
```
default void addCaretListener(CaretListener listener,
                              Disposable parentDisposable)
```
    Adds a listener for receiving notifications about caret movement and caret addition/removal. The listener is removed when the given parent disposable is disposed.
    
    Parameters:
    
    listener - the listener instance.
  - removeCaretListener
```
void removeCaretListener(CaretListener listener)
```
    Removes a listener for receiving notifications about caret movement and caret addition/removal
    
    Parameters:
    
    listener - the listener instance.
  - getVisualLineStart
```
default int getVisualLineStart()
```
    Returns:
    
    document offset for the start of the logical line where caret is located
  - getVisualLineEnd
```
default int getVisualLineEnd()
```
    Returns:
    
    document offset that points to the first symbol shown at the next visual line after the one with caret on it
  - getTextAttributes
```
TextAttributes getTextAttributes()
```
    Returns visual representation of caret (e.g. background color).
    
    Returns:
    
    Caret attributes.
  - supportsMultipleCarets
```
boolean supportsMultipleCarets()
```
    Tells whether multiple coexisting carets are supported by this CaretModel instance. Multiple carets are not supported when the corresponding Editor instance is a facade over a Swing JTextArea component.
  - getCurrentCaret
```
Caret getCurrentCaret()
```
    Returns current caret - the one, query and update methods in the model operate at the moment. In the current implementation this is either an iteration-current caret within the context of runForEachCaret(CaretAction) method, or the 'primary' caret without that context. Users runForEachCaret(CaretAction) method should use caret parameter passed to CaretAction.perform(Caret) method instead of this method, as the definition of current caret (as well as caret instance operated on by model methods) can potentially change.
  - getPrimaryCaret
```
Caret getPrimaryCaret()
```
    Returns the 'primary' caret.
  - getCaretCount
```
int getCaretCount()
```
    Returns number of carets currently existing in the document
  - getAllCarets
```
java.util.List<Caret> getAllCarets()
```
    Returns all carets currently existing in the document, ordered by their visual position in editor.
  - getCaretAt
```
Caret getCaretAt(VisualPosition pos)
```
    Returns a caret at the given position in the document, or null, if there's no caret there.
  - addCaret
```
default Caret addCaret(VisualPosition pos)
```
    Same as addCaret(VisualPosition, boolean) with true as a makePrimary boolean parameter value.
  - addCaret
```
Caret addCaret(VisualPosition pos,
               boolean makePrimary)
```
    Adds a new caret at the given position, and returns corresponding Caret instance. Locations outside of possible values for the given document are trimmed automatically. Newly added caret will become a primary caret if and only if makePrimary value is true. Does nothing if multiple carets are not supported, a caret already exists at specified location or selection of existing caret includes the specified location, null is returned in this case.
  - addCaret
```
Caret addCaret(LogicalPosition pos,
               boolean makePrimary)
```
    Adds a new caret at the given position, and returns corresponding Caret instance. Locations outside of possible values for the given document are trimmed automatically. Newly added caret will become a primary caret if and only if makePrimary value is true. Does nothing if multiple carets are not supported, a caret already exists at specified location or selection of existing caret includes the specified location, null is returned in this case.
  - removeCaret
```
boolean removeCaret(Caret caret)
```
    Removes a given caret if it's recognized by the model and is not the only existing caret in the document, returning true. false is returned if any of the above condition doesn't hold, and the removal cannot happen.
  - removeSecondaryCarets
```
void removeSecondaryCarets()
```
    Removes all carets except the 'primary' one from the document.
  - setCaretsAndSelections
```
void setCaretsAndSelections(java.util.List<? extends CaretState> caretStates)
```
    Sets the number of carets, their positions and selection ranges according to the provided data. Null values for caret position or selection boundaries will mean that corresponding caret's position and/or selection won't be changed.
    System selection will be updated, if such feature is supported by current editor.
    
    Throws:
    
    java.lang.IllegalArgumentException - if caretStates list is empty, or if it contains more than one element and editor doesn't support multiple carets
    
    See Also:
    
    supportsMultipleCarets(), getCaretsAndSelections(), setCaretsAndSelections(List, boolean)
  - setCaretsAndSelections
```
void setCaretsAndSelections(java.util.List<? extends CaretState> caretStates,
                            boolean updateSystemSelection)
```
    Sets the number of carets, their positions and selection ranges according to the provided data. Null values for caret position or selection boundaries will mean that corresponding caret's position and/or selection won't be changed.
    System selection will be updated, if such feature is supported by current editor and corresponding invocation parameter is set to true.
    
    Throws:
    
    java.lang.IllegalArgumentException - if caretStates list is empty, or if it contains more than one element and editor doesn't support multiple carets
    
    See Also:
    
    supportsMultipleCarets(), getCaretsAndSelections()
  - getCaretsAndSelections
```
java.util.List<CaretState> getCaretsAndSelections()
```
    Returns the current positions of all carets and their selections. The order of entries in the returned list does not necessarily correspond to the order of getAllCarets() method results. Passing the result of this method to setCaretsAndSelections(List) will restore the state of carets, including the internal caret order, in particular, the caret, that was primary when this method was called, will be the primary one after corresponding setCaretsAndSelections(List) invocation.
    
    See Also:
    
    setCaretsAndSelections(List)
  - runForEachCaret
```
void runForEachCaret(CaretAction action)
```
    Same as runForEachCaret(CaretAction, boolean) with reverseOrder set to false
  - runForEachCaret
```
void runForEachCaret(CaretAction action,
                     boolean reverseOrder)
```
    Executes the given task for each existing caret. Set of carets to iterate over is determined in the beginning and is not affected by the potential carets addition or removal by the task being executed. At the end, merging of carets and selections is performed, so that no two carets will occur at the same logical position and no two selection will overlap after this method is finished.
    Carets are iterated in position order (top-to-bottom) if reverseOrder is false, and in reverse order if it's true.
    It's possible to call this method not from EDT (for read-only operations). Caret merging is not performed in this case, and no notifications to CaretActionListener-s are sent.
  - addCaretActionListener
```
void addCaretActionListener(CaretActionListener listener,
                            Disposable disposable)
```
    Adds a listener which will be notified before and after all-caret operations are performed by runForEachCaret(CaretAction) and runForEachCaret(CaretAction, boolean). Listeners will be notified only if those methods are invoked from EDT (non-EDT invocations are not allowed to change caret state anyway).
  - runBatchCaretOperation
```
void runBatchCaretOperation(java.lang.Runnable runnable)
```
    Executes the given task, performing caret merging afterwards. Caret merging will not happen until the operation is finished.

Interface CaretModel

Method Summary

Method Detail

moveCaretRelatively

moveToLogicalPosition

moveToVisualPosition

moveToOffset

moveToOffset

isUpToDate

getLogicalPosition

getVisualPosition

getOffset

addCaretListener

addCaretListener

removeCaretListener

getVisualLineStart

getVisualLineEnd

getTextAttributes

supportsMultipleCarets

getCurrentCaret

getPrimaryCaret

getCaretCount

getAllCarets

getCaretAt

addCaret

addCaret

addCaret

removeCaret

removeSecondaryCarets

setCaretsAndSelections

setCaretsAndSelections

getCaretsAndSelections

runForEachCaret

runForEachCaret

addCaretActionListener

runBatchCaretOperation