is new.
java.lang.Objectjava.awt.geom.RectangularShape
java.awt.geom.Rectangle2D
java.awt.Rectangle
javax.swing.text.DefaultCaret
public class DefaultCaret
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 getSelectionHighlighter 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 TM has been added to the java.beans package. Please see XMLEncoder .
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from class java.awt.geom. Rectangle2D |
|---|
| Rectangle2D.Double , Rectangle2D.Float |
| Field Summary | |
|---|---|
| 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 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 | |
|---|---|
|
DefaultCaret
() Constructs a default caret. |
|
| Method Summary | ||
|---|---|---|
| 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.
|
|
|
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. |
|
Position.Bias
|
getMarkBias
()
Returns the bias of the mark.
|
|
| protected Highlighter.HighlightPainter |
getSelectionPainter
() Gets the painter for the Highlighter. |
|
| int |
getUpdatePolicy
() Gets the caret movement policy on document updates. |
|
| void |
install
(
JTextComponent
c) Called when the UI is being installed into the interface of a JTextComponent. |
|
| boolean |
isActive
() Determines if the caret is currently active. |
|
| boolean |
isSelectionVisible
() Checks whether the current selection is visible. |
|
| boolean |
isVisible
() Indicates whether or not the caret is currently visible. |
|
| void |
mouseClicked
(
MouseEvent
e) Called when the mouse is clicked. |
|
| void |
mouseDragged
(
MouseEvent
e) Moves the caret position according to the mouse pointer's current location. |
|
| void |
mouseEntered
(
MouseEvent
e) Called when the mouse enters a region. |
|
| void |
mouseExited
(
MouseEvent
e) Called when the mouse exits a region. |
|
| void |
mouseMoved
(
MouseEvent
e) Called when the mouse is moved. |
|
| void |
mousePressed
(
MouseEvent
e) If button 1 is pressed, this is implemented to request focus on the associated text component, and to set the caret position. |
|
| void |
mouseReleased
(
MouseEvent
e) Called when the mouse is released. |
|
| protected void |
moveCaret
(
MouseEvent
e) Tries to move the position of the caret from the coordinates of a mouse event, using viewToModel(). |
|
| void |
moveDot
(int dot) Moves the caret position to
the specified position, with a forward bias.
|
|
void
|
moveDot
(int dot,
Position.Bias
Moves the caret position to the specified position, with the specified bias.
|
|
| void |
paint
(
Graphics
g) Renders the caret as a vertical line. |
|
| protected void |
positionCaret
(
MouseEvent
e) Tries to set the position of the caret from the coordinates of a mouse event, using viewToModel(). |
|
| void |
removeChangeListener
(
ChangeListener
l) Removes a listener that was tracking caret position changes. |
|
| protected void |
repaint
() Cause the caret to be painted. |
|
| void |
setBlinkRate
(int rate) Sets the caret blink rate. |
|
| void |
setDot
(int dot) Sets the caret position and mark to
the specified position, with a forward bias.
|
|
void
|
setDot
(int dot,
Position.Bias
Sets the caret position and mark to the specified position, with the specified bias.
|
|
| void |
setMagicCaretPosition
(
Point
p) Saves the current caret position. |
|
| void |
setSelectionVisible
(boolean vis) Changes the selection visibility. |
|
| void |
setUpdatePolicy
(int policy) Sets the caret movement policy on the document updates. |
|
| void |
setVisible
(boolean e) Sets the caret visibility, and repaints the caret. |
|
| String |
toString
() Returns a String representing this Rectangle and its values. |
|
| Methods inherited from class java.awt. Rectangle |
|---|
| add , add , add , contains , contains , contains , contains , createIntersection , createUnion , getBounds , getBounds2D , getHeight , getLocation , getSize , getWidth , getX , getY , grow , inside , intersection , intersects , isEmpty , move , outcode , reshape , resize , setBounds , setBounds , setLocation , setLocation , setRect , setSize , setSize , 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 |
|---|
public static final int UPDATE_WHEN_ON_EDT
public static final int NEVER_UPDATE
public static final int ALWAYS_UPDATE
protected EventListenerList listenerList
protected transient ChangeEvent changeEvent
| Constructor Detail |
|---|
public DefaultCaret()
| Method Detail |
|---|
public void setUpdatePolicy(int policy)
The following update policies are allowed:
The default property value is UPDATE_WHEN_ON_EDT.
public int getUpdatePolicy()
protected final JTextComponent getComponent()
protected final void repaint()
This method is thread safe, although most Swing methods are not. Please see
How to Use Threads
Threads and Swing
for more information.
protected void damage(Rectangle r)
protected void adjustVisibility(Rectangle nloc)
protected Highlighter.HighlightPainter getSelectionPainter()
protected void positionCaret(MouseEvent e)
protected void moveCaret(MouseEvent e)
public void focusGained(FocusEvent e)
public void focusLost(FocusEvent e)
public void mouseClicked(MouseEvent e)
public void mousePressed(MouseEvent e)
public void mouseReleased(MouseEvent e)
public void mouseEntered(MouseEvent e)
public void mouseExited(MouseEvent e)
public void mouseDragged(MouseEvent e)
public void mouseMoved(MouseEvent e)
public void paint(Graphics g)
If there are multiple text directions present in the associated document, a flag indicating the caret bias will be rendered. This will occur only if the associated document is a subclass of AbstractDocument and there are multiple bidi levels present in the bidi element structure (i.e. the text has multiple directions associated with it).
public void install(JTextComponent c)
public void deinstall(JTextComponent c)
public void addChangeListener(ChangeListener l)
public void removeChangeListener(ChangeListener l)
public ChangeListener[] getChangeListeners()
protected void fireStateChanged()
public <T extends EventListener> T[] getListeners(Class<T> listenerType)
You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultCaret c for its change listeners with the following code:
ChangeListener[] cls = (ChangeListener[])(c.getListeners(ChangeListener.class));If no such listeners exist, this method returns an empty array.
public void setSelectionVisible(boolean vis)
public boolean isSelectionVisible()
public boolean isActive()
This method returns whether or not the Caret is currently in a blinking state. It does not provide information as to whether it is currently blinked on or off. To determine if the caret is currently painted use the isVisible method.
public boolean isVisible()
Subclasses that wish to render a different flashing caret should override paint and only paint the caret if this method returns true.
public void setVisible(boolean e)
Here's a list showing the potential return values of both isActive and isVisible after calling this method:
setVisible(true) :
setVisible(false) :
public void setBlinkRate(int rate)
public int getBlinkRate()
public int getDot()
>=
public int getMark()
>=
public void setDot(int dot)
the specified position, with a forward bias.
>=
#setDot(int, javax.swing.text.Position),
Caret.setDot(int)
public void moveDot(int dot)
the specified position, with a forward bias.
>=
moveDot(int, javax.swing.text.Position.Bias)
,
Caret.moveDot(int)
moveDot
public void
moveDot
(int dot,
Position.Bias
dotBias)
Moves the caret position to the specified position, with the specified bias.
Parameters:
dot - the position >= 0
dotBias - the bias for this position, not null
Throws:
IllegalArgumentException
- if the bias is null
Since:
1.6
See Also:
Caret.moveDot(int)
setDot
public void
setDot
(int dot,
Position.Bias
dotBias)
Sets the caret position and mark to the specified position, with the specified bias. This implicitly sets the selection range to zero.
Parameters:
dot - the position >= 0
dotBias - the bias for this position, not null
Throws:
IllegalArgumentException
- if the bias is null
Since:
1.6
See Also:
Caret.setDot(int)
getDotBias
public
Position.Bias
getDotBias
()
Returns the bias of the caret position.
Returns:
the bias of the caret position
Since:
1.6
getMarkBias
public
Position.Bias
getMarkBias
()
Returns the bias of the mark.
Returns:
the bias of the mark
Since:
1.6
public void setMagicCaretPosition(Point p)
public Point getMagicCaretPosition()
public boolean equals(Object obj)
public String toString()