EditorCaret (Editor Library 2)

java.lang.Object
- org.netbeans.api.editor.caret.EditorCaret

All Implemented Interfaces:

Caret
```
public final class EditorCaret
extends Object
implements Caret
```
Extension to standard Swing caret used by all NetBeans editors.
It supports multi-caret editing mode where an arbitrary number of carets is placed at arbitrary positions throughout a document. In this mode each caret is described by its CaretInfo object.
The Caret interface is not aware of multiple carets and a call to setDot(int) will only retain a single caret. For multiple carets a call to moveDot(int) will move the last caret only (but it retains other existing carets).
The caret works over text components having AbstractDocument based document.

Since:

2.6

Constructor Summary

Constructors
Constructor and Description

EditorCaret()

Constructors
Constructor and Description
`EditorCaret()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`addCaret(Position dotPos, Position.Bias dotBias, Position markPos, Position.Bias markBias)` Create a new caret at the given position with a possible selection.
`int`	`addCarets(List<Position> dotAndMarkPosPairs, List<Position.Bias> dotAndMarkBiases)` Add multiple carets at once.
`void`	`addChangeListener(ChangeListener l)` Adds listener to track caret position changes (to fulfil `Caret` interface).
`void`	`addEditorCaretListener(EditorCaretListener listener)` Adds listener to track caret changes in detail.
`void`	`deinstall(JTextComponent c)`
`int`	`getBlinkRate()`
`CaretInfo`	`getCaretAt(int offset)` Get information about the caret at the specified offset.
`List<CaretInfo>`	`getCarets()` Get information about all existing carets in the order they were created.
`int`	`getDot()` Get dot offset of the last created caret in the underlying document.
`Position.Bias`	`getDotBias()` Get a bias of the dot position which is either `Position.Bias.Forward` or `Position.Bias.Backward` depending on whether the caret biases towards the next character or previous one.
`CaretInfo`	`getLastCaret()` Get info about the most recently created caret.
`Point`	`getMagicCaretPosition()`
`int`	`getMark()` Get mark offset of the last created caret in the underlying document.
`Position.Bias`	`getMarkBias()` Get a bias of the mark position which is either `Position.Bias.Forward` or `Position.Bias.Backward` depending on whether the caret biases towards the next character or previous one.
`static NavigationFilter`	`getNavigationFilter(JTextComponent component, MoveCaretsOrigin origin)` Returns the navigation filter for a certain operation.
`List<CaretInfo>`	`getSortedCarets()` Get information about all existing carets sorted by dot positions in ascending order.
`void`	`install(JTextComponent c)`
`boolean`	`isSelectionVisible()`
`boolean`	`isVisible()` Determines if the caret is currently visible (it may be blinking depending on settings).
`int`	`moveCarets(CaretMoveHandler moveHandler)` Move multiple carets or create/modify selections.
`int`	`moveCarets(CaretMoveHandler moveHandler, MoveCaretsOrigin origin)` Move multiple carets or create/modify selections, specifies the originating operation.
`void`	`moveDot(int offset)` Moves the caret position (dot) to some other position, leaving behind the mark.
`void`	`moveDot(int offset, Position.Bias bias, MoveCaretsOrigin origin)` Moves the caret position (dot) to some other position, leaving behind the mark.
`void`	`paint(Graphics g)`
`void`	`removeChangeListener(ChangeListener l)` Removes listener to track caret position changes (to fulfil `Caret` interface).
`void`	`removeEditorCaretListener(EditorCaretListener listener)`
`int`	`removeLastCaret()` Remove last added caret (determined by `EditorCaret.getLastCaret()`).
`int`	`replaceCarets(List<Position> dotAndMarkPosPairs, List<Position.Bias> dotAndMarkBiases)` Replace all current carets with the new ones.
`int`	`retainLastCaretOnly()` Switch to single caret mode by removing all carets except the last caret.
`void`	`setBlinkRate(int rate)`
`void`	`setDot(int offset)` Assign a new offset to the caret in the underlying document.
`void`	`setDot(int offset, Position.Bias bias, MoveCaretsOrigin origin)` Assign a new offset to the caret and identify the operation which originated the caret movement.
`void`	`setMagicCaretPosition(Point p)`
`static void`	`setNavigationFilter(JTextComponent component, MoveCaretsOrigin origin, NavigationFilter naviFilter)` Sets navigation filter for a certain operation type, defined by `MoveCaretsOrigin`.
`void`	`setSelectionVisible(boolean v)`
`void`	`setVisible(boolean visible)` Sets the caret visibility, and repaints the caret.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - EditorCaret
```
public EditorCaret()
```
- Method Detail
  - getDot
```
public int getDot()
```
    Get dot offset of the last created caret in the underlying document.
    
    Specified by:
    
    getDot in interface Caret
    
    Returns:
    
    dot offset >=0
  - getDotBias
```
@NonNull
public Position.Bias getDotBias()
```
    Get a bias of the dot position which is either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret biases towards the next character or previous one. The bias is always forward for non bidirectional text document.
    
    Returns:
    
    either forward or backward bias.
    
    Since:
    
    2.12
  - getMark
```
public int getMark()
```
    Get mark offset of the last created caret in the underlying document. If there is a selection, the mark will not be the same as the dot.
    
    Specified by:
    
    getMark in interface Caret
    
    Returns:
    
    mark offset >=0
  - getMarkBias
```
@NonNull
public Position.Bias getMarkBias()
```
    Get a bias of the mark position which is either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret biases towards the next character or previous one. The bias is always forward for non bidirectional text document.
    
    Returns:
    
    either forward or backward bias.
    
    Since:
    
    2.12
  - getCarets
```
@NonNull
public List<CaretInfo> getCarets()
```
    Get information about all existing carets in the order they were created.
    The list always has at least one item. The last caret (last item of the list) is the most recent caret.
    The list is a snapshot of the current state of the carets. The list content itself and its contained caret infos are guaranteed not change after subsequent calls to caret API or document modifications.
    The list is nonmodifiable.
    This method should be called with document's read-lock acquired which will guarantee stability of CaretInfo.getDot() and CaretInfo.getMark() and prevent caret merging as a possible effect of document modifications.
    
    Returns:
    
    copy of caret list with size >= 1 containing information about all carets.
  - getSortedCarets
```
@NonNull
public List<CaretInfo> getSortedCarets()
```
    Get information about all existing carets sorted by dot positions in ascending order.
    If some of the carets are ComplexPositions their order will reflect the increasing split offset.
    The list is a snapshot of the current state of the carets. The list content itself and its contained caret infos are guaranteed not change after subsequent calls to caret API or document modifications.
    The list is nonmodifiable.
    This method should be called with document's read-lock acquired which will guarantee stability of CaretInfo.getDot() and CaretInfo.getMark() and prevent caret merging as a possible effect of document modifications.
    
    Returns:
    
    copy of caret list with size >= 1 sorted by dot positions in ascending order.
  - getLastCaret
```
@NonNull
public CaretInfo getLastCaret()
```
    Get info about the most recently created caret.
    For normal mode this is the only caret returned by EditorCaret.getCarets().
    For multi-caret mode this is the last item in the list returned by EditorCaret.getCarets().
    
    Returns:
    
    last caret (the most recently added caret).
  - getCaretAt
```
@CheckForNull
public CaretInfo getCaretAt(int offset)
```
    Get information about the caret at the specified offset.
    
    Parameters:
    
    offset - the offset of the caret
    
    Returns:
    
    CaretInfo for the caret at offset, null if there is no caret or the offset is invalid
  - setDot
```
public void setDot(int offset)
```
    Assign a new offset to the caret in the underlying document.
    This method implicitly sets the selection range to zero.
    If multiple carets are present this method retains only last caret which then moves to the given offset.
    
    Specified by:
    
    setDot in interface Caret
    
    Parameters:
    
    offset -
    
    See Also:
    
    Caret.setDot(int)
  - setDot
```
public void setDot(int offset,
                   Position.Bias bias,
                   MoveCaretsOrigin origin)
```
    Assign a new offset to the caret and identify the operation which originated the caret movement.
    In addition to EditorCaret.setDot(int), the caller may identify the operation that originated the caret movement. This information is received by NavigationFilters or ChangeListeners and may be used to react or modify the caret movements.
    Use null or MoveCaretsOrigin.DEFAULT if the operation not known. Use MoveCaretsOrigin.DIRECT_NAVIGATION action type to identify simple navigational actions (pg up, pg down, left, right, ...).
    
    Parameters:
    
    offset - new offset for the caret
    
    bias - new bias for the caret. Use either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret should bias towards the next character or previous one. Use forward bias for non-bidirectional text document.
    
    origin - specifies the operation which caused the caret to move.
    
    Since:
    
    2.10
    
    See Also:
    
    EditorCaret.setDot(int)
  - moveDot
```
public void moveDot(int offset)
```
    Moves the caret position (dot) to some other position, leaving behind the mark. This is useful for making selections.
    If multiple carets are present this method retains all carets and moves the dot of the last caret to the given offset.
    
    Specified by:
    
    moveDot in interface Caret
    
    Parameters:
    
    offset -
    
    See Also:
    
    Caret.moveDot(int)
  - moveDot
```
public void moveDot(int offset,
                    Position.Bias bias,
                    MoveCaretsOrigin origin)
```
    Moves the caret position (dot) to some other position, leaving behind the mark.
    In addition to EditorCaret.setDot(int), the caller may identify the operation that originated the caret movement. This information is received by NavigationFilters or EditorCaretListeners and may be used to react or modify the caret movements.
    Use null or MoveCaretsOrigin.DEFAULT if the operation not known. Use MoveCaretsOrigin.DIRECT_NAVIGATION action type to identify simple navigational actions (pg up, pg down, left, right, ...).
    
    Parameters:
    
    offset - new offset for the caret
    
    bias - new bias for the caret. Use either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret should bias towards the next character or previous one. Use forward bias for non-bidirectional text document.
    
    origin - specifies the operation which caused the caret to move.
    
    Since:
    
    2.10
    
    See Also:
    
    EditorCaret.moveDot(int)
  - moveCarets
```
public int moveCarets(@NonNull
                      CaretMoveHandler moveHandler)
```
    Move multiple carets or create/modify selections.
    For performance reasons this is made as a single transaction over the caret with only one change event being fired.
    Note that the move handler does not permit to add or remove carets - this has to be performed by other methods present in this class (as another transaction over the editor caret).
```
 
   // Go one line up with all carets
   editorCaret.moveCarets(new CaretMoveHandler() {
     @Override public void moveCarets(CaretMoveContext context) {
       for (CaretInfo caretInfo : context.getOriginalSortedCarets()) {
         try {
           int dot = caretInfo.getDot();
           dot = Utilities.getPositionAbove(target, dot, p.x);
           Position dotPos = doc.createPosition(dot);
           context.setDot(caretInfo, dotPos);
         } catch (BadLocationException e) {
           // the position stays the same
         }
       }
     }
   });
 
 
```
    Parameters:
    
    moveHandler - non-null move handler to perform the changes. The handler's methods will be given a context to operate on.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was cancelled due to the caret not being installed in any text component or no document installed in the text component.
  - moveCarets
```
public int moveCarets(@NonNull
                      CaretMoveHandler moveHandler,
                      MoveCaretsOrigin origin)
```
    Move multiple carets or create/modify selections, specifies the originating operation.
    In addition to EditorCaret.moveCarets(org.netbeans.spi.editor.caret.CaretMoveHandler), the caller may specify what operation causes the caret movements in the `origin' parameter, see MoveCaretsOrigin class. This information is received by NavigationFilters or EditorCaretListeners and may be used to react or modify the caret movements.
    Use null or MoveCaretsOrigin.DEFAULT if the operation not known. Use MoveCaretsOrigin.DIRECT_NAVIGATION action type to identify simple navigational actions (pg up, pg down, left, right, ...).
    See the EditorCaret.moveCarets(org.netbeans.spi.editor.caret.CaretMoveHandler) for detailed description of how carets are moved.
    
    Parameters:
    
    moveHandler - handler which moves individual carets
    
    origin - description of the originating operation. Use null or MoveCaretsOrigin.DEFAULT for default/unspecified operation.
    
    Returns:
    
    difference between number of carets, see EditorCaret.moveCarets(org.netbeans.spi.editor.caret.CaretMoveHandler).
    
    Since:
    
    2.10
    
    See Also:
    
    EditorCaret.moveCarets(org.netbeans.spi.editor.caret.CaretMoveHandler)
  - addCaret
```
public int addCaret(@NonNull
                    Position dotPos,
                    @NonNull
                    Position.Bias dotBias,
                    @NonNull
                    Position markPos,
                    @NonNull
                    Position.Bias markBias)
```
    Create a new caret at the given position with a possible selection.
    The caret will become the last caret of the list returned by EditorCaret.getCarets().
    This method requires the caller to have either read lock or write lock acquired over the underlying document.
```
 
   editorCaret.addCaret(pos, pos); // Add a new caret at pos.getOffset()
 
   Position pos2 = doc.createPosition(pos.getOffset() + 2);
   // Add a new caret with selection starting at pos and extending to pos2 with caret located at pos2
   editorCaret.addCaret(pos2, pos);
   // Add a new caret with selection starting at pos and extending to pos2 with caret located at pos
   editorCaret.addCaret(pos, pos2);
 
 
```
    Parameters:
    
    dotPos - position of the newly created caret.
    
    dotBias - bias of the new caret. Use either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret should bias towards the next character or previous one. Use forward bias for non-bidirectional text document.
    
    markPos - beginning of the selection (the other end is dotPos) or the same position like dotPos for no selection. The markPos may have higher offset than dotPos to select in a backward direction.
    
    markBias - bias of the begining of the selection. Use either Position.Bias.Forward or Position.Bias.Backward depending on whether the caret should bias towards the next character or previous one. Use forward bias for non-bidirectional text document.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was canceled due to the caret not being installed in any text component or no document installed in the text component.
    Note that adding a new caret to offset where another caret is already located may lead or no document installed in the text component.
  - addCarets
```
public int addCarets(@NonNull
                     List<Position> dotAndMarkPosPairs,
                     List<Position.Bias> dotAndMarkBiases)
```
    Add multiple carets at once.
    It is similar to calling EditorCaret.addCaret(javax.swing.text.Position, javax.swing.text.Position.Bias, javax.swing.text.Position, javax.swing.text.Position.Bias) multiple times but this method is more efficient (it only fires caret change once).
    This method requires the caller to have either read lock or write lock acquired over the underlying document.
```
 
   List<Position> pairs = new ArrayList<>();
   pairs.add(dotPos);
   pairs.add(dotPos);
   pairs.add(dot2Pos);
   pairs.add(mark2Pos);
   // Add caret located at dotPos.getOffset() and another one with selection
   // starting at mark2Pos and extending to dot2Pos with caret located at dot2Pos
   editorCaret.addCaret(pairs);
 
 
```
    Parameters:
    
    dotAndMarkPosPairs - list of position pairs consisting of dot position and mark position (selection start position) which may be the same position like the dot if the particular caret has no selection. The list must have even size.
    
    dotAndMarkBiases - list of position biases (corresponding to the dot and mark positions in the previous parameter) or null may be passed if all dotAndMarkPosPairs positions should have a forward bias.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was canceled due to the caret not being installed in any text component or no document installed in the text component.
    
    See Also:
    
    EditorCaret.addCaret(javax.swing.text.Position, javax.swing.text.Position.Bias, javax.swing.text.Position, javax.swing.text.Position.Bias)
  - replaceCarets
```
public int replaceCarets(@NonNull
                         List<Position> dotAndMarkPosPairs,
                         List<Position.Bias> dotAndMarkBiases)
```
    Replace all current carets with the new ones.
    This method requires the caller to have either read lock or write lock acquired over the underlying document.
    
    Parameters:
    
    dotAndMarkPosPairs - list of position pairs consisting of dot position and mark position (selection start position) which may be the same position like dot if the particular caret has no selection. The list must have even size.
    
    dotAndMarkBiases - list of position biases (corresponding to the dot and mark positions in the previous parameter) or null may be passed if all dotAndMarkPosPairs positions should have a forward bias.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was cancelled due to the caret not being installed in any text component or no document installed in the text component.
  - removeLastCaret
```
public int removeLastCaret()
```
    Remove last added caret (determined by EditorCaret.getLastCaret()).
    If there is just one caret the method has no effect.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was cancelled due to the caret not being installed in any text component or no document installed in the text component.
  - retainLastCaretOnly
```
public int retainLastCaretOnly()
```
    Switch to single caret mode by removing all carets except the last caret.
    
    Returns:
    
    difference between current count of carets and the number of carets when the operation started. Returns Integer.MIN_VALUE if the operation was cancelled due to the caret not being installed in any text component or no document installed in the text component.
  - addEditorCaretListener
```
public void addEditorCaretListener(@NonNull
                                   EditorCaretListener listener)
```
    Adds listener to track caret changes in detail.
    
    Parameters:
    
    listener - non-null listener.
  - addChangeListener
```
public void addChangeListener(@NonNull
                              ChangeListener l)
```
    Adds listener to track caret position changes (to fulfil Caret interface).
    
    Specified by:
    
    addChangeListener in interface Caret
  - removeEditorCaretListener
```
public void removeEditorCaretListener(@NonNull
                                      EditorCaretListener listener)
```
  - removeChangeListener
```
public void removeChangeListener(@NonNull
                                 ChangeListener l)
```
    Removes listener to track caret position changes (to fulfil Caret interface).
    
    Specified by:
    
    removeChangeListener in interface Caret
  - isVisible
```
public boolean isVisible()
```
    Determines if the caret is currently visible (it may be blinking depending on settings).
    Caret becomes visible after setVisible(true) gets called on it.
    
    Specified by:
    
    isVisible in interface Caret
    
    Returns:
    
    true if visible else false
  - setVisible
```
public void setVisible(boolean visible)
```
    Sets the caret visibility, and repaints the caret.
    
    Specified by:
    
    setVisible in interface Caret
    
    Parameters:
    
    visible - the visibility specifier
    
    See Also:
    
    Caret.setVisible(boolean)
  - isSelectionVisible
```
public boolean isSelectionVisible()
```
    Specified by:
    
    isSelectionVisible in interface Caret
  - setSelectionVisible
```
public void setSelectionVisible(boolean v)
```
    Specified by:
    
    setSelectionVisible in interface Caret
  - install
```
public void install(JTextComponent c)
```
    Specified by:
    
    install in interface Caret
  - deinstall
```
public void deinstall(JTextComponent c)
```
    Specified by:
    
    deinstall in interface Caret
  - paint
```
public void paint(Graphics g)
```
    Specified by:
    
    paint in interface Caret
  - setMagicCaretPosition
```
public void setMagicCaretPosition(Point p)
```
    Specified by:
    
    setMagicCaretPosition in interface Caret
  - getMagicCaretPosition
```
public final Point getMagicCaretPosition()
```
    Specified by:
    
    getMagicCaretPosition in interface Caret
  - setBlinkRate
```
public void setBlinkRate(int rate)
```
    Specified by:
    
    setBlinkRate in interface Caret
  - getNavigationFilter
```
@CheckForNull
public static NavigationFilter getNavigationFilter(@NonNull
                                                                 JTextComponent component,
                                                                 @NonNull
                                                                 MoveCaretsOrigin origin)
```
    Returns the navigation filter for a certain operation. NavigationFilter can be registered to receive only limited set of operations. This method returns the filter for the specified operation. Use MoveCaretsOrigin.DEFAULT to get text component's navigation filter (equivalent to JTextComponent.getNavigationFilter(). That filter receives all caret movements.
    
    Parameters:
    
    component - the component whose filter should be returned
    
    origin - the operation description
    
    Returns:
    
    the current navigation filter.
    
    Since:
    
    2.10
  - setNavigationFilter
```
public static void setNavigationFilter(JTextComponent component,
                                       MoveCaretsOrigin origin,
                                       @NullAllowed
                                       NavigationFilter naviFilter)
```
    Sets navigation filter for a certain operation type, defined by MoveCaretsOrigin.
    The registered filter will receive only those caret movements, which correspond to the passed MoveCaretsOrigin. To receive all caret movements, register for MoveCaretsOrigin.DEFAULT or use JTextComponent.setNavigationFilter(javax.swing.text.NavigationFilter).
    All the key part(s) of MoveCaretOrigin of a caret operation and `origin' parameter in this function must match in order for the filter to be invoked.
    The NavigationFilter implementation may downcast the passed FilterBypass parameter to NavigationFilterBypass to get full infomration about the movement.
    
    Parameters:
    
    component - the component which will use the filter
    
    origin - the origin
    
    naviFilter - the installed filter
    
    Since:
    
    2.10
    
    See Also:
    
    JTextComponent.setNavigationFilter(javax.swing.text.NavigationFilter), NavigationFilterBypass
  - getBlinkRate
```
public int getBlinkRate()
```
    Specified by:
    
    getBlinkRate in interface Caret

Class EditorCaret

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

EditorCaret

Method Detail

getDot

getDotBias

getMark

getMarkBias

getCarets

getSortedCarets

getLastCaret

getCaretAt

setDot

setDot

moveDot

moveDot

moveCarets

moveCarets

addCaret

addCarets

replaceCarets

removeLastCaret

retainLastCaretOnly

addEditorCaretListener

addChangeListener

removeEditorCaretListener

removeChangeListener

isVisible

setVisible

isSelectionVisible

setSelectionVisible

install

deinstall

paint

setMagicCaretPosition

getMagicCaretPosition

setBlinkRate

getNavigationFilter

setNavigationFilter

getBlinkRate