OpenJDK 27 · javax.swing.text.DefaultCaret · APIdia, the JavaDoc alternative

A default implementation of Caret. The caret is rendered as a vertical line in the color specified by the CaretColor property of the associated JTextComponent. It can blink at the rate specified by the BlinkRate property.

This implementation expects two sources of asynchronous notification. The timer thread fires asynchronously, and causes the caret to simply repaint the most recent bounding box. The caret also tracks change as the document is modified. Typically this will happen on the event dispatch thread as a result of some mouse or keyboard event. The caret behavior on both synchronous and asynchronous documents updates is controlled by UpdatePolicy property. The repaint of the new caret location will occur on the event thread in any case, as calls to modelToView are only safe on the event thread.

The caret acts as a mouse and focus listener on the text component it has been installed in, and defines the caret semantics based upon those events. The listener methods can be reimplemented to change the semantics. By default, the first mouse button will be used to set focus and caret position. Dragging the mouse pointer with the first mouse button will sweep out a selection that is contiguous in the model. If the associated text component is editable, the caret will become visible when focus is gained, and invisible when focus is lost.

The Highlighter bound to the associated text component is used to render the selection by default. Selection appearance can be customized by supplying a painter to use for the highlights. By default a painter is used that will render a solid color as specified in the associated text component in the SelectionColor property. This can easily be changed by reimplementing the getSelectionPainter method.

A customized caret appearance can be achieved by reimplementing the paint method. If the paint method is changed, the damage method should also be reimplemented to cause a repaint for the area needed to render the caret. The caret extends the Rectangle class which is used to hold the bounding box for where the caret was last rendered. This enables the caret to repaint in a thread-safe manner when the caret moves without making a call to modelToView which is unstable between model updates and view repair (i.e. the order of delivery to DocumentListeners is not guaranteed).

The magic caret position is set to null when the caret position changes. A timer is used to determine the new location (after the caret change). When the timer fires, if the magic caret position is still null it is reset to the current caret position. Any actions that change the caret position and want the magic caret position to remain the same, must remember the magic caret position, change the cursor, and then set the magic caret position to its original value. This has the benefit that only actions that want the magic caret position to persist (such as open/down) need to know about it.

Warning

Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans package. Please see java.beans.XMLEncoder.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private class	DefaultCaret.DefaultFilterBypass
pack-priv class	DefaultCaret.Handler
pack-priv class	DefaultCaret.SafeScroller

Field Summary

Modifier and Type	Field and Description
pack-priv boolean	active
public static final int	ALWAYS_UPDATE Indicates that the caret position is to be always updated accordingly to the document changes regardless whether the document updates are performed on the Event Dispatching Thread or not.
private float	aspectRatio
private int	caretWidth The width of the caret in pixels.
protected transient ChangeEvent	changeEvent The change event for the model.
pack-priv JTextComponent	component
pack-priv int	dot
pack-priv transient Position.Bias	dotBias
pack-priv boolean	dotLTR
private transient NavigationFilter.FilterBypass	filterBypass
private transient int[]	flagXPoints
private transient int[]	flagYPoints
pack-priv Timer	flasher
private boolean	forceCaretPositionChange If this is true, the location of the dot is updated regardless of the current location.
pack-priv transient DefaultCaret.Handler	handler
private boolean	isBlinkRateSaved
protected EventListenerList	listenerList The event listener list.
pack-priv Point	magicCaretPosition
pack-priv int	mark
pack-priv transient Position.Bias	markBias
pack-priv boolean	markLTR
public static final int	NEVER_UPDATE Indicates that the caret should remain at the same absolute position in the document regardless of any document updates, except when the document length becomes less than the current caret position due to removal.
private boolean	ownsSelection This is used to indicate if the caret currently owns the selection.
private int	savedBlinkRate
private transient MouseEvent	selectedWordEvent holds last MouseEvent which caused the word selection
pack-priv Object	selectionTag
pack-priv boolean	selectionVisible
private static transient Action	selectLine
private static transient Action	selectWord
private transient boolean	shouldHandleRelease Whether or not mouseReleased should adjust the caret and focus.
public static final int	UPDATE_WHEN_ON_EDT Indicates that the caret position is to be updated only when document changes are performed on the Event Dispatching Thread.
pack-priv int	updatePolicy
pack-priv boolean	visible

Inherited from java.awt.Rectangle:: height width x y

Constructor Summary

Access	Constructor and Description
public	DefaultCaret() Constructs a default caret.

Method Summary

Modifier and Type	Method and Description
private boolean	_contains(int X, int Y, int W, int H)
public void	addChangeListener(ChangeListener the listener l) Implements javax.swing.text.Caret.addChangeListener. Adds a listener to track whenever the caret position has been changed.
private void	adjustCaret(MouseEvent e) Adjusts the caret location based on the MouseEvent.
pack-priv void	adjustCaretAndFocus(MouseEvent e)
private void	adjustFocus(boolean if true indicates requestFocusInWindow should be used inWindow) Adjusts the focus, if necessary.
protected void	adjustVisibility(Rectangle the new position to scroll to nloc) Scrolls the associated view (if necessary) to make the caret visible.
pack-priv void	changeCaretPosition(int dot, Position.Bias dotBias) Sets the caret position (dot) to a new location.
protected synchronized void	damage(Rectangle the current location of the caret r) Damages the area surrounding the caret to cause it to be repainted in a new location.
public void	deinstall(JTextComponent the component c) Implements javax.swing.text.Caret.deinstall. Called when the UI is being removed from the interface of a JTextComponent.
private void	ensureValidPosition() This is invoked after the document changes to verify the current dot/mark is valid.
public boolean	Returns: `true` if the objects are equal; `false` otherwise equals(Object the object to compare this font with obj) Overrides java.awt.Rectangle.equals. Compares this object to the specified object.
protected void	fireStateChanged() Notifies all listeners that have registered interest for notification on this event type.
public void	focusGained(FocusEvent the focus event e) Implements java.awt.event.FocusListener.focusGained. Called when the component containing the caret gains focus.
public void	focusLost(FocusEvent the focus event e) Implements java.awt.event.FocusListener.focusLost. Called when the component containing the caret loses focus.
public int	Returns: the delay in milliseconds. If this is zero the caret will not blink. getBlinkRate() Implements javax.swing.text.Caret.getBlinkRate. Gets the caret blink rate.
pack-priv int	getCaretWidth(int height)
public ChangeListener[]	Returns: all of this caret's `ChangeListener`s or an empty array if no change listeners are currently registered getChangeListeners() Returns an array of all the change listeners registered on this caret.
private ClipboardOwner	getClipboardOwner()
protected final JTextComponent	Returns: the component getComponent() Gets the text editor component that this caret is bound to.
public int	Returns: the position >= 0 getDot() Implements javax.swing.text.Caret.getDot. Fetches the current position of the caret.
public Position.Bias	Returns: the bias of the caret position getDotBias() Returns the bias of the caret position.
private NavigationFilter.FilterBypass	getFilterBypass()
public < the listener type T extends EventListener> T[]	Returns: an array of all objects registered as `FooListener`s on this component, or an empty array if no such listeners have been added getListeners(Class<T> the type of listeners requested listenerType) Returns an array of all the objects currently registered as `FooListener`s upon this caret.
public Point	Returns: the position see #setMagicCaretPosition getMagicCaretPosition() Implements javax.swing.text.Caret.getMagicCaretPosition. Gets the saved caret position.
public int	Returns: the position >= 0 getMark() Implements javax.swing.text.Caret.getMark. Fetches the current position of the mark.
public Position.Bias	Returns: the bias of the mark getMarkBias() Returns the bias of the mark.
protected Highlighter.HighlightPainter	Returns: the painter getSelectionPainter() Gets the painter for the Highlighter.
private Clipboard	getSystemSelection()
public int	Returns: one of the following values : `UPDATE_WHEN_ON_EDT`, `NEVER_UPDATE`, `ALWAYS_UPDATE` getUpdatePolicy() Gets the caret movement policy on document updates.
pack-priv Position.Bias	guessBiasForOffset(int offset, Position.Bias lastBias, boolean lastLTR)
pack-priv void	handleMoveDot(int dot, Position.Bias dotBias)
pack-priv void	handleSetDot(int dot, Position.Bias dotBias)
public void	install(JTextComponent the component c) Implements javax.swing.text.Caret.install. Called when the UI is being installed into the interface of a JTextComponent.
public boolean	Returns: `true` if active else `false` isActive() Determines if the caret is currently active.
pack-priv boolean	isDotLeftToRight()
pack-priv boolean	isMarkLeftToRight()
pack-priv boolean	isPositionLTR(int position, Position.Bias bias)
public boolean	Returns: true if the selection is visible isSelectionVisible() Implements javax.swing.text.Caret.isSelectionVisible. Checks whether the current selection is visible.
public boolean	Returns: true if visible else false isVisible() Implements javax.swing.text.Caret.isVisible. Indicates whether or not the caret is currently visible.
public void	mouseClicked(MouseEvent the mouse event e) Implements java.awt.event.MouseListener.mouseClicked. Called when the mouse is clicked.
public void	mouseDragged(MouseEvent the mouse event e) Implements java.awt.event.MouseMotionListener.mouseDragged. Moves the caret position according to the mouse pointer's current location.
public void	mouseEntered(MouseEvent the mouse event e) Implements java.awt.event.MouseListener.mouseEntered. Called when the mouse enters a region.
public void	mouseExited(MouseEvent the mouse event e) Implements java.awt.event.MouseListener.mouseExited. Called when the mouse exits a region.
public void	mouseMoved(MouseEvent the mouse event e) Implements java.awt.event.MouseMotionListener.mouseMoved. Called when the mouse is moved.
public void	mousePressed(MouseEvent the mouse event e) Implements java.awt.event.MouseListener.mousePressed. If button 1 is pressed, this is implemented to request focus on the associated text component, and to set the caret position.
public void	mouseReleased(MouseEvent the mouse event e) Implements java.awt.event.MouseListener.mouseReleased. Called when the mouse is released.
protected void	moveCaret(MouseEvent the mouse event e) Tries to move the position of the caret from the coordinates of a mouse event, using viewToModel().
public void	moveDot(int the position >= 0 dot) Implements javax.swing.text.Caret.moveDot. Moves the caret position to the specified position, with a forward bias.
public void	moveDot(int the position >= 0 dot, Position.Bias the bias for this position, not `null` dotBias) Moves the caret position to the specified position, with the specified bias.
public void	paint(Graphics the graphics context g) Implements javax.swing.text.Caret.paint. Renders the caret as a vertical line.
protected void	positionCaret(MouseEvent the mouse event e) Tries to set the position of the caret from the coordinates of a mouse event, using viewToModel().
private void	readObject(ObjectInputStream s)
public void	removeChangeListener(ChangeListener the listener l) Implements javax.swing.text.Caret.removeChangeListener. Removes a listener that was tracking caret position changes.
protected final synchronized void	repaint() Cause the caret to be painted.
pack-priv void	repaintNewCaret() Repaints the new caret position, with the assumption that this is happening on the event thread so that calling `modelToView` is safe.
private void	selectWord(MouseEvent e) Selects word based on the MouseEvent
public void	setBlinkRate(int the rate in milliseconds, 0 to stop blinking rate) Implements javax.swing.text.Caret.setBlinkRate. Sets the caret blink rate.
public void	setDot(int the position >= 0 dot) Implements javax.swing.text.Caret.setDot. Sets the caret position and mark to the specified position, with a forward bias.
public void	setDot(int the position >= 0 dot, Position.Bias the bias for this position, not `null` dotBias) Sets the caret position and mark to the specified position, with the specified bias.
public void	setMagicCaretPosition(Point the position p) Implements javax.swing.text.Caret.setMagicCaretPosition. Saves the current caret position.
public void	setSelectionVisible(boolean the new visibility vis) Implements javax.swing.text.Caret.setSelectionVisible. Changes the selection visibility.
public void	setUpdatePolicy(int one of the following values : `UPDATE_WHEN_ON_EDT`, `NEVER_UPDATE`, `ALWAYS_UPDATE` policy) Sets the caret movement policy on the document updates.
public void	setVisible(boolean the visibility specifier e) Implements javax.swing.text.Caret.setVisible. Sets the caret visibility, and repaints the caret.
public String	toString() Overrides java.awt.Rectangle.toString. Returns a `String` representing this `Rectangle` and its values.
private void	updateSystemSelection()
private void	writeObject(ObjectOutputStream s)

public Class DefaultCaret

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary