Class EditorCaret

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.

getDot

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.

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

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

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.

getCaretAt

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.

setDot

Assign a new offset to the caret and identify the operation which
originated the caret movement.

In addition to 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.

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.

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.

moveDot

Moves the caret position (dot) to some other position, leaving behind the
mark.

In addition to 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.

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.

moveCarets

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

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.

addCaret

Create a new caret at the given position with a possible selection.
The caret will become the last caret of the list returned by 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

Add multiple carets at once.
It is similar to calling #addCaret(javax.swing.text.Position, javax.swing.text.Position)
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.

replaceCarets

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