javax.swing.text

Class DefaultCaret

public class DefaultCaret extends Rectangle implements Caret, FocusListener, MouseListener, MouseMotionListener

The default implementation of the {@link Caret} interface.

Field Summary
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 {@link #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.

Constructor Summary
	DefaultCaret() Creates a new `DefaultCaret` instance.

Method Summary
void	addChangeListener(ChangeListener listener) Registers a {@link 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 {@link ChangeListener}s 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 {@link ChangeListener}s 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 {@link 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 {@link 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.

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

changeEvent

protected ChangeEvent changeEvent

The ChangeEvent that is fired by {@link #fireStateChanged()}.

listenerList

protected EventListenerList listenerList

Stores all registered event listeners.

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

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

Constructor Detail

DefaultCaret

public DefaultCaret()

Creates a new DefaultCaret instance.

Method Detail

addChangeListener

public void addChangeListener(ChangeListener listener)

Registers a {@link ChangeListener} that is notified whenever that state of this Caret changes.

Parameters: listener the listener to register to this caret

adjustVisibility

protected void adjustVisibility(Rectangle rect)

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

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

deinstall

public void deinstall(JTextComponent c)

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

Parameters: c the text component from which to install this caret

fireStateChanged

protected void fireStateChanged()

Notifies all registered {@link ChangeListener}s that the state of this Caret has changed.

focusGained

public void focusGained(FocusEvent event)

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

Parameters: event the FocusEvent

focusLost

public void focusLost(FocusEvent event)

Sets the caret to invisible.

Parameters: event the FocusEvent

getBlinkRate

public int getBlinkRate()

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

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

getChangeListeners

public ChangeListener[] getChangeListeners()

Returns all registered {@link ChangeListener}s of this Caret.

Returns: all registered {@link ChangeListener}s of this Caret

getComponent

protected final JTextComponent getComponent()

Returns the JTextComponent on which this Caret is installed.

Returns: the JTextComponent on which this Caret is installed

getDot

public int getDot()

Returns the current position of this Caret within the Document.

Returns: the current position of this Caret within the Document

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

getMagicCaretPosition

public Point getMagicCaretPosition()

Returns the current visual position of this Caret.

Returns: the current visual position of this Caret

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.

Returns: the current position of the mark

getSelectionPainter

protected Highlighter.HighlightPainter getSelectionPainter()

Returns the {@link Highlighter.HighlightPainter} that should be used to paint the selection.

Returns: the {@link Highlighter.HighlightPainter} that should be used to paint the selection

getUpdatePolicy

public int getUpdatePolicy()

Gets the caret update policy.

Returns: the caret update policy.

Since: 1.5

install

public void install(JTextComponent c)

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

Parameters: c the text component on which to install this caret

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 {@link #isVisible()}.

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

Since: 1.5

isSelectionVisible

public boolean isSelectionVisible()

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

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

isVisible

public boolean isVisible()

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

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

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.

Parameters: event the MouseEvent describing the click operation

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.

Parameters: event the MouseEvent describing the drag operation

mouseEntered

public void mouseEntered(MouseEvent event)

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

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.

Parameters: event the MouseEvent describing the mouse operation

mouseMoved

public void mouseMoved(MouseEvent event)

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

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.

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.

Parameters: event the MouseEvent describing the mouse operation

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

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 {@link NavigationFilter} installed the caret will call the corresponding method of that object.

Parameters: dot the location where to move the dot

paint

public void paint(Graphics g)

Paints this Caret using the specified Graphics context.

Parameters: g the graphics context to use

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

removeChangeListener

public void removeChangeListener(ChangeListener listener)

Removes a {@link ChangeListener} from the list of registered listeners.

Parameters: listener the listener to remove

repaint

protected final void repaint()

Causes the Caret to repaint itself.

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.

Parameters: rate the new blink rate to set

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 {@link NavigationFilter} installed the caret will call the corresponding method of that object.

Parameters: dot the new position to be set

setMagicCaretPosition

public void setMagicCaretPosition(Point p)

Sets the current visual position of this Caret.

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

setSelectionVisible

public void setSelectionVisible(boolean v)

Sets the visiblity state of the selection.

Parameters: v true if the selection should be visible, false otherwise

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

setVisible

public void setVisible(boolean v)

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

Parameters: v the visibility to set