Module java.desktop
Package javax.swing.text

Class DefaultCaret

java.lang.Object
java.awt.geom.RectangularShape
java.awt.geom.Rectangle2D
java.awt.Rectangle
javax.swing.text.DefaultCaret
All Implemented Interfaces:
FocusListener, MouseListener, MouseMotionListener, Shape, Serializable, Cloneable, EventListener, Caret
Direct Known Subclasses:
BasicTextUI.BasicCaret
public class DefaultCaret extends Rectangle implements Caret, FocusListener, MouseListener, MouseMotionListener
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 XMLEncoder.

See Also:
Caret

  • Nested Class Summary

    Nested classes/interfaces declared in class java.awt.geom.Rectangle2D

    Rectangle2D.Double, Rectangle2D.Float

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static 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.
    protected ChangeEvent
    changeEvent
    The change event for the model.
    protected EventListenerList
    listenerList
    The event listener list.
    static 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.
    static 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.

    Fields declared in class java.awt.Rectangle

    height, width, x, y

    Fields declared in class java.awt.geom.Rectangle2D

    OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP

  • Constructor Summary

    Constructors
    Constructor
    Description
    DefaultCaret()
    Constructs a default caret.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addChangeListener​(ChangeListener l)
    Adds a listener to track whenever the caret position has been changed.
    protected void
    adjustVisibility​(Rectangle nloc)
    Scrolls the associated view (if necessary) to make the caret visible.
    protected void
    damage​(Rectangle r)
    Damages the area surrounding the caret to cause it to be repainted in a new location.
    void
    deinstall​(JTextComponent c)
    Called when the UI is being removed from the interface of a JTextComponent.
    boolean
    equals​(Object obj)
    Compares this object to the specified object.
    protected void
    fireStateChanged()
    Notifies all listeners that have registered interest for notification on this event type.
    void
    focusGained​(FocusEvent e)
    Called when the component containing the caret gains focus.
    void
    focusLost​(FocusEvent e)
    Called when the component containing the caret loses focus.
    int
    getBlinkRate()
    Gets the caret blink rate.
    ChangeListener[]
    getChangeListeners()
    Returns an array of all the change listeners registered on this caret.
    protected JTextComponent
    getComponent()
    Gets the text editor component that this caret is is bound to.
    int
    getDot()
    Fetches the current position of the caret.
    Position.Bias
    getDotBias()
    Returns the bias of the caret position.
    <T extends EventListener>
    T[]
    getListeners​(Class<T> listenerType)
    Returns an array of all the objects currently registered as FooListeners upon this caret.
    Point
    getMagicCaretPosition()
    Gets the saved caret position.
    int
    getMark()
    Fetches the current position of the mark.