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

The default implementation of the Caret interface.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.geom.Rectangle2D

Rectangle2D.Double, Rectangle2D.Float

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALWAYS_UPDATE Indicates the Caret position should always be updated after Document changes even if the updates are not performed on the Event Dispatching thread.
protected ChangeEvent	changeEvent The ChangeEvent that is fired by fireStateChanged().
protected EventListenerList	listenerList Stores all registered event listeners.
static int	NEVER_UPDATE Indicates the Caret position should not be changed unless the Document length becomes less than the Caret position, in which case the Caret is moved to the end of the Document.
static int	UPDATE_WHEN_ON_EDT Indicates the Caret position should be updated only if Document changes are made on the Event Dispatcher thread.

Fields inherited from class java.awt.Rectangle

height, width, x, y

Fields inherited from class java.awt.geom.Rectangle2D

OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP

Constructor Summary

Constructors

Constructor and Description
DefaultCaret() Creates a new DefaultCaret instance.

Method Summary

Methods

Modifier and Type	Method and Description
void	addChangeListener(ChangeListener listener) Registers a ChangeListener that is notified whenever that state of this Caret changes.
protected void	adjustVisibility(Rectangle rect) Adjusts the text component so that the caret is visible.
protected void	damage(Rectangle r) Updates the carets rectangle properties to the specified rectangle and repaints the caret.
void	deinstall(JTextComponent c) Deinstalls this Caret from the specified JTextComponent.
protected void	fireStateChanged() Notifies all registered ChangeListeners that the state of this Caret has changed.
void	focusGained(FocusEvent event) Sets the caret to visible if the text component is editable.
void	focusLost(FocusEvent event) Sets the caret to invisible.
int	getBlinkRate() Returns the blink rate of this Caret in milliseconds.
ChangeListener[]	getChangeListeners() Returns all registered ChangeListeners of this Caret.
protected JTextComponent	getComponent() Returns the JTextComponent on which this Caret is installed.
int	getDot() Returns the current position of this Caret within the Document.
<T extends EventListener> T[]	getListeners(Class<T> listenerType) Returns all registered event listeners of the specified type.
Point	getMagicCaretPosition() Returns the current visual position of this Caret.
int	getMark() Returns the current position of the mark.
protected Highlighter.HighlightPainter	getSelectionPainter() Returns the Highlighter.HighlightPainter that should be used to paint the selection.
int	getUpdatePolicy() Gets the caret update policy.
void	install(JTextComponent c) Installs this Caret on the specified JTextComponent.
boolean	isActive() Returns true if this Caret is blinking, and false if not.
boolean	isSelectionVisible() Returns true if the selection is currently visible, false otherwise.
boolean	isVisible() Returns true if this Caret is currently visible, and false if it is not.
void	mouseClicked(MouseEvent event) When the click is received from Button 1 then the following actions are performed here: If we receive a double click, the caret position (dot) is set to the position associated to the mouse click and the word at this location is selected.
void	mouseDragged(MouseEvent event) Moves the caret position when the mouse is dragged over the text component, modifying the selectiony.
void	mouseEntered(MouseEvent event) Indicates that the mouse has entered the text component.
void	mouseExited(MouseEvent event) Indicates that the mouse has exited the text component.
void	mouseMoved(MouseEvent event) Indicates a mouse movement over the text component.
void	mousePressed(MouseEvent event) If the button 1 is pressed, the caret position is updated to the position of the mouse click and the text component requests the input focus if it is enabled.
void	mouseReleased(MouseEvent event) Indicates that a mouse button has been released on the text component.
protected void	moveCaret(MouseEvent event) Moves the caret to the position specified in the MouseEvent.
void	moveDot(int dot) Moves the dot location without touching the mark.
void	paint(Graphics g) Paints this Caret using the specified Graphics context.
protected void	positionCaret(MouseEvent event) Repositions the caret to the position specified in the MouseEvent.
void	removeChangeListener(ChangeListener listener) Removes a ChangeListener from the list of registered listeners.
protected void	repaint() Causes the Caret to repaint itself.
void	setBlinkRate(int rate) Sets the blink rate of this Caret in milliseconds.
void	setDot(int dot) Sets the current position of this Caret within the Document.
void	setMagicCaretPosition(Point p) Sets the current visual position of this Caret.
void	setSelectionVisible(boolean v) Sets the visiblity state of the selection.
void	setUpdatePolicy(int policy) Sets the Caret update policy.
void	setVisible(boolean v) Sets the visibility state of the caret.

Methods inherited from class java.awt.Rectangle

add, add, add, contains, contains, contains, contains, createIntersection, createUnion, equals, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, toString, translate, union

Methods inherited from class java.awt.geom.Rectangle2D

add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union

Methods inherited from class java.awt.geom.RectangularShape

clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.awt.Shape

contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects

Field Detail

ALWAYS_UPDATE

public static final int ALWAYS_UPDATE

Indicates the Caret position should always be updated after Document changes even if the updates are not performed on the Event Dispatching thread.

Since:

1.5

See Also:

Constant Field Values

NEVER_UPDATE

public static final int NEVER_UPDATE

Indicates the Caret position should not be changed unless the Document length becomes less than the Caret position, in which case the Caret is moved to the end of the Document.

Since:

1.5

See Also:

Constant Field Values

UPDATE_WHEN_ON_EDT

public static final int UPDATE_WHEN_ON_EDT

Indicates the Caret position should be updated only if Document changes are made on the Event Dispatcher thread.

Since:

1.5

See Also:

Constant Field Values

changeEvent

protected ChangeEvent changeEvent

The ChangeEvent that is fired by fireStateChanged().

listenerList

protected EventListenerList listenerList

Stores all registered event listeners.

Constructor Detail

DefaultCaret

public DefaultCaret()

Creates a new DefaultCaret instance.

Method Detail

setUpdatePolicy

public void setUpdatePolicy(int policy)

Sets the Caret update policy.

Parameters:

policy - the new policy. Valid values are: ALWAYS_UPDATE: always update the Caret position, even when Document updates don't occur on the Event Dispatcher thread. NEVER_UPDATE: don't update the Caret position unless the Document length becomes less than the Caret position (then update the Caret to the end of the Document). UPDATE_WHEN_ON_EDT: update the Caret position when the Document updates occur on the Event Dispatcher thread. This is the default.

Throws:

IllegalArgumentException - if policy is not one of the above.

Since:

1.5

getUpdatePolicy

public int getUpdatePolicy()

Gets the caret update policy.

Returns:

the caret update policy.

Since:

1.5

mouseDragged

public void mouseDragged(MouseEvent event)

Moves the caret position when the mouse is dragged over the text component, modifying the selectiony.

When the text component where the caret is installed is disabled, the selection is not change but you can still scroll the text and update the caret's location.

Specified by:

mouseDragged in interface MouseMotionListener

Parameters:

event - the MouseEvent describing the drag operation

mouseMoved

public void mouseMoved(MouseEvent event)

Indicates a mouse movement over the text component. Does nothing here.

Specified by:

mouseMoved in interface MouseMotionListener

Parameters:

event - the MouseEvent describing the mouse operation

mouseClicked

public void mouseClicked(MouseEvent event)

When the click is received from Button 1 then the following actions are performed here:

• If we receive a double click, the caret position (dot) is set to the position associated to the mouse click and the word at this location is selected. If there is no word at the pointer the gap is selected instead.
• If we receive a triple click, the caret position (dot) is set to the position associated to the mouse click and the line at this location is selected.

Specified by:

mouseClicked in interface MouseListener

Parameters:

event - the MouseEvent describing the click operation

mouseEntered

public void mouseEntered(MouseEvent event)

Indicates that the mouse has entered the text component. Nothing is done here.

Specified by:

mouseEntered in interface MouseListener

Parameters:

event - the MouseEvent describing the mouse operation

mouseExited

public void mouseExited(MouseEvent event)

Indicates that the mouse has exited the text component. Nothing is done here.

Specified by:

mouseExited in interface MouseListener

Parameters:

event - the MouseEvent describing the mouse operation

mousePressed

public void mousePressed(MouseEvent event)

If the button 1 is pressed, the caret position is updated to the position of the mouse click and the text component requests the input focus if it is enabled. If the SHIFT key is held down, the caret will be moved, which might select the text between the old and new location.

Specified by:

mousePressed in interface MouseListener

Parameters:

event - the MouseEvent describing the press operation

mouseReleased

public void mouseReleased(MouseEvent event)

Indicates that a mouse button has been released on the text component. Nothing is done here.

Specified by:

mouseReleased in interface MouseListener

Parameters:

event - the MouseEvent describing the mouse operation

focusGained

public void focusGained(FocusEvent event)

Sets the caret to visible if the text component is editable.

Specified by:

focusGained in interface FocusListener

Parameters:

event - the FocusEvent

focusLost

public void focusLost(FocusEvent event)

Sets the caret to invisible.

Specified by:

focusLost in interface FocusListener

Parameters:

event - the FocusEvent

moveCaret

protected void moveCaret(MouseEvent event)

Moves the caret to the position specified in the MouseEvent. This will cause a selection if the dot and mark are different.

Parameters:

event - the MouseEvent from which to fetch the position

positionCaret

protected void positionCaret(MouseEvent event)

Repositions the caret to the position specified in the MouseEvent.

Parameters:

event - the MouseEvent from which to fetch the position

deinstall

public void deinstall(JTextComponent c)

Deinstalls this Caret from the specified JTextComponent. This removes any listeners that have been registered by this Caret.

Specified by:

deinstall in interface Caret

Parameters:

c - the text component from which to install this caret

install

public void install(JTextComponent c)

Installs this Caret on the specified JTextComponent. This registers a couple of listeners on the text component.

Specified by:

install in interface Caret

Parameters:

c - the text component on which to install this caret

setMagicCaretPosition

public void setMagicCaretPosition(Point p)

Sets the current visual position of this Caret.

Specified by:

setMagicCaretPosition in interface Caret

Parameters:

p - the Point to use for the saved location. May be null to indicate that there is no visual location

getMagicCaretPosition

public Point getMagicCaretPosition()

Returns the current visual position of this Caret.

Specified by:

getMagicCaretPosition in interface Caret

Returns:

the current visual position of this Caret

See Also:

setMagicCaretPosition(java.awt.Point)

getMark

public int getMark()

Returns the current position of the mark. The mark marks the location in the Document that is the end of a selection. If there is no selection, the mark is the same as the dot.

Specified by:

getMark in interface Caret

Returns:

the current position of the mark

setSelectionVisible

public void setSelectionVisible(boolean v)

Sets the visiblity state of the selection.

Specified by:

setSelectionVisible in interface Caret

Parameters:

v - true if the selection should be visible, false otherwise

isSelectionVisible

public boolean isSelectionVisible()

Returns true if the selection is currently visible, false otherwise.

Specified by:

isSelectionVisible in interface Caret

Returns:

true if the selection is currently visible, false otherwise

repaint

protected final void repaint()

Causes the Caret to repaint itself.

paint

public void paint(Graphics g)

Paints this Caret using the specified Graphics context.

Specified by:

paint in interface Caret

Parameters:

g - the graphics context to use

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)

Returns all registered event listeners of the specified type.

Parameters:

listenerType - the type of listener to return

Returns:

all registered event listeners of the specified type

addChangeListener

public void addChangeListener(ChangeListener listener)

Registers a ChangeListener that is notified whenever that state of this Caret changes.

Specified by:

addChangeListener in interface Caret

Parameters:

listener - the listener to register to this caret

removeChangeListener

public void removeChangeListener(ChangeListener listener)

Removes a ChangeListener from the list of registered listeners.

Specified by:

removeChangeListener in interface Caret

Parameters:

listener - the listener to remove

getChangeListeners

public ChangeListener[] getChangeListeners()

Returns all registered ChangeListeners of this Caret.

Returns:

all registered ChangeListeners of this Caret

fireStateChanged

protected void fireStateChanged()

Notifies all registered ChangeListeners that the state of this Caret has changed.

getComponent

protected final JTextComponent getComponent()

Returns the JTextComponent on which this Caret is installed.

Returns:

the JTextComponent on which this Caret is installed

getBlinkRate

public int getBlinkRate()

Returns the blink rate of this Caret in milliseconds. A value of 0 means that the caret does not blink.

Specified by:

getBlinkRate in interface Caret

Returns:

the blink rate of this Caret or 0 if this caret does not blink

setBlinkRate

public void setBlinkRate(int rate)

Sets the blink rate of this Caret in milliseconds. A value of 0 means that the caret does not blink.

Specified by:

setBlinkRate in interface Caret

Parameters:

rate - the new blink rate to set

getDot

public int getDot()

Returns the current position of this Caret within the Document.

Specified by:

getDot in interface Caret

Returns:

the current position of this Caret within the Document

moveDot

public void moveDot(int dot)

Moves the dot location without touching the mark. This is used when making a selection.

If the underlying text component has a NavigationFilter installed the caret will call the corresponding method of that object.

Specified by:

moveDot in interface Caret

Parameters:

dot - the location where to move the dot

See Also:

setDot(int)

setDot

public void setDot(int dot)

Sets the current position of this Caret within the Document. This also sets the mark to the new location.

If the underlying text component has a NavigationFilter installed the caret will call the corresponding method of that object.

Specified by:

setDot in interface Caret

Parameters:

dot - the new position to be set

See Also:

moveDot(int)

isActive

public boolean isActive()

Returns true if this Caret is blinking, and false if not. The returned value is independent of the visiblity of this Caret as returned by isVisible().

Returns:

true if this Caret is blinking, and false if not.

Since:

1.5

See Also:

isVisible()

isVisible

public boolean isVisible()

Returns true if this Caret is currently visible, and false if it is not.

Specified by:

isVisible in interface Caret

Returns:

true if this Caret is currently visible, and false if it is not

setVisible

public void setVisible(boolean v)

Sets the visibility state of the caret. true shows the Caret, false hides it.

Specified by:

setVisible in interface Caret

Parameters:

v - the visibility to set

getSelectionPainter

protected Highlighter.HighlightPainter getSelectionPainter()

Returns the Highlighter.HighlightPainter that should be used to paint the selection.

Returns:

the Highlighter.HighlightPainter that should be used to paint the selection

damage

protected void damage(Rectangle r)

Updates the carets rectangle properties to the specified rectangle and repaints the caret.

Parameters:

r - the rectangle to set as the caret rectangle

adjustVisibility

protected void adjustVisibility(Rectangle rect)

Adjusts the text component so that the caret is visible. This default implementation simply calls JComponent.scrollRectToVisible(Rectangle) on the text component. Subclasses may wish to change this.