FocusListener
, MouseListener
, MouseMotionListener
, Shape
, Serializable
, Cloneable
, EventListener
, Caret
BasicTextUI.BasicCaret
public class DefaultCaret extends Rectangle implements Caret, FocusListener, MouseListener, MouseMotionListener
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
.
Caret
Rectangle2D.Double, Rectangle2D.Float
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.
|
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
Constructor | Description |
---|---|
DefaultCaret() |
Constructs a default caret.
|
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> |
getListeners(Class<T> listenerType) |
Returns an array of all the objects currently registered
as
FooListener s
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 dotBias) |
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 dotBias) |
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. |
finalize, getClass, notify, notifyAll, wait, wait, wait
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
add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union
clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects
public static final int UPDATE_WHEN_ON_EDT
setUpdatePolicy(int)
,
getUpdatePolicy()
,
Constant Field Valuespublic static final int NEVER_UPDATE
setUpdatePolicy(int)
,
getUpdatePolicy()
,
Constant Field Valuespublic static final int ALWAYS_UPDATE
setUpdatePolicy(int)
,
getUpdatePolicy()
,
Constant Field Valuesprotected EventListenerList listenerList
protected transient ChangeEvent changeEvent
public void setUpdatePolicy(int policy)
BACKSPACE
is typed then caret decreases its absolute
position due to removal of a character before it. Sometimes
it may be useful to turn off the caret position updates so that
the caret stays at the same absolute position within the
document position regardless of any document updates.
The following update policies are allowed:
NEVER_UPDATE
: the caret stays at the same
absolute position in the document regardless of any document
updates, except when document length becomes less than
the current caret position due to removal. In that case caret
position is adjusted to the end of the document.
The caret doesn't try to keep itself visible by scrolling
the associated view when using this policy. ALWAYS_UPDATE
: the caret always tracks document
changes. For regular changes it increases its position
if an insertion occurs before or at its current position,
and decreases position if a removal occurs before
its current position. For undo/redo updates it is always
moved to the position where update occurred. The caret
also tries to keep itself visible by calling
adjustVisibility
method.UPDATE_WHEN_ON_EDT
: acts like ALWAYS_UPDATE
if the document updates are performed on the Event Dispatching Thread
and like NEVER_UPDATE
if updates are performed on
other thread.
The default property value is UPDATE_WHEN_ON_EDT
.
policy
- one of the following values : UPDATE_WHEN_ON_EDT
,
NEVER_UPDATE
, ALWAYS_UPDATE
IllegalArgumentException
- if invalid value is passedgetUpdatePolicy()
,
adjustVisibility(java.awt.Rectangle)
,
UPDATE_WHEN_ON_EDT
,
NEVER_UPDATE
,
ALWAYS_UPDATE
public int getUpdatePolicy()
UPDATE_WHEN_ON_EDT
,
NEVER_UPDATE
, ALWAYS_UPDATE
setUpdatePolicy(int)
,
UPDATE_WHEN_ON_EDT
,
NEVER_UPDATE
,
ALWAYS_UPDATE
protected final JTextComponent getComponent()
protected final void repaint()
This method is thread safe, although most Swing methods are not. Please see Concurrency in Swing for more information.
protected void damage(Rectangle r)
r
- the current location of the caretpaint(java.awt.Graphics)
protected void adjustVisibility(Rectangle nloc)
nloc
- the new position to scroll toprotected Highlighter.HighlightPainter getSelectionPainter()
protected void positionCaret(MouseEvent e)
e
- the mouse eventprotected void moveCaret(MouseEvent e)
e
- the mouse eventpublic void focusGained(FocusEvent e)
focusGained
in interface FocusListener
e
- the focus eventFocusListener.focusGained(java.awt.event.FocusEvent)
public void focusLost(FocusEvent e)
focusLost
in interface FocusListener
e
- the focus eventFocusListener.focusLost(java.awt.event.FocusEvent)
public void mouseClicked(MouseEvent e)
mouseClicked
in interface MouseListener
e
- the mouse eventMouseListener.mouseClicked(java.awt.event.MouseEvent)
public void mousePressed(MouseEvent e)
mousePressed
in interface MouseListener
e
- the mouse eventMouseListener.mousePressed(java.awt.event.MouseEvent)
public void mouseReleased(MouseEvent e)
mouseReleased
in interface MouseListener
e
- the mouse eventMouseListener.mouseReleased(java.awt.event.MouseEvent)
public void mouseEntered(MouseEvent e)
mouseEntered
in interface MouseListener
e
- the mouse eventMouseListener.mouseEntered(java.awt.event.MouseEvent)
public void mouseExited(MouseEvent e)
mouseExited
in interface MouseListener
e
- the mouse eventMouseListener.mouseExited(java.awt.event.MouseEvent)
public void mouseDragged(MouseEvent e)
mouseDragged
in interface MouseMotionListener
e
- the mouse eventMouseMotionListener.mouseDragged(java.awt.event.MouseEvent)
public void mouseMoved(MouseEvent e)
mouseMoved
in interface MouseMotionListener
e
- the mouse eventMouseMotionListener.mouseMoved(java.awt.event.MouseEvent)
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).
paint
in interface Caret
g
- the graphics contextdamage(java.awt.Rectangle)
public void install(JTextComponent c)
install
in interface Caret
c
- the componentCaret.install(javax.swing.text.JTextComponent)
public void deinstall(JTextComponent c)
deinstall
in interface Caret
c
- the componentCaret.deinstall(javax.swing.text.JTextComponent)
public void addChangeListener(ChangeListener l)
addChangeListener
in interface Caret
l
- the listenerCaret.addChangeListener(javax.swing.event.ChangeListener)
public void removeChangeListener(ChangeListener l)
removeChangeListener
in interface Caret
l
- the listenerCaret.removeChangeListener(javax.swing.event.ChangeListener)
public ChangeListener[] getChangeListeners()
ChangeListener
s
or an empty
array if no change listeners are currently registeredaddChangeListener(javax.swing.event.ChangeListener)
,
removeChangeListener(javax.swing.event.ChangeListener)
protected void fireStateChanged()
EventListenerList
public <T extends EventListener> T[] getListeners(Class<T> listenerType)
FooListener
s
upon this caret.
FooListener
s are registered using the
addFooListener
method.
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.
T
- the listener typelistenerType
- the type of listeners requestedFooListener
s on this component,
or an empty array if no such
listeners have been addedClassCastException
- if listenerType
doesn't specify a class or interface that implements
java.util.EventListener
getChangeListeners()
public void setSelectionVisible(boolean vis)
setSelectionVisible
in interface Caret
vis
- the new visibilitypublic boolean isSelectionVisible()
isSelectionVisible
in interface Caret
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.
true
if active else false
isVisible()
public boolean isVisible()
isActive
indicates whether
or not the caret is in a blinking state, such that it can
be visible, and isVisible
indicates whether or not
the caret is actually visible.
Subclasses that wish to render a different flashing caret should override paint and only paint the caret if this method returns true.
isVisible
in interface Caret
Caret.isVisible()
,
isActive()
public void setVisible(boolean e)
isVisible
and isActive
.
Calling this method with a value of true
activates the
caret blinking. Setting it to false
turns it completely off.
To determine whether the blinking is active, you should call
isActive
. In effect, isActive
is an
appropriate corresponding "getter" method for this one.
isVisible
can be used to fetch the current
visibility status of the caret, meaning whether or not it is currently
painted. This status will change as the caret blinks on and off.
Here's a list showing the potential return values of both
isActive
and isVisible
after calling this method:
setVisible(true)
:
setVisible(false)
:
setVisible
in interface Caret
e
- the visibility specifierisActive()
,
Caret.setVisible(boolean)
public void setBlinkRate(int rate)
setBlinkRate
in interface Caret
rate
- the rate in milliseconds, 0 to stop blinkingCaret.setBlinkRate(int)
public int getBlinkRate()
getBlinkRate
in interface Caret
Caret.getBlinkRate()
public int getDot()
getDot
in interface Caret
Caret.getDot()
public int getMark()
getMark
in interface Caret
Caret.getMark()
public void setDot(int dot)
setDot
in interface Caret
dot
- the position >= 0setDot(int, Position.Bias)
,
Caret.setDot(int)
public void moveDot(int dot)
moveDot
in interface Caret
dot
- the position >= 0moveDot(int, javax.swing.text.Position.Bias)
,
Caret.moveDot(int)
public void moveDot(int dot, Position.Bias dotBias)
dot
- the position >= 0dotBias
- the bias for this position, not null
IllegalArgumentException
- if the bias is null
Caret.moveDot(int)
public void setDot(int dot, Position.Bias dotBias)
dot
- the position >= 0dotBias
- the bias for this position, not null
IllegalArgumentException
- if the bias is null
Caret.setDot(int)
public Position.Bias getDotBias()
public Position.Bias getMarkBias()
public void setMagicCaretPosition(Point p)
setMagicCaretPosition
in interface Caret
p
- the positiongetMagicCaretPosition()
public Point getMagicCaretPosition()
getMagicCaretPosition
in interface Caret
Caret.setMagicCaretPosition(java.awt.Point)
public boolean equals(Object obj)
equals
in class Rectangle
obj
- the object to compare this font withtrue
if the objects are equal;
false
otherwiseObject.hashCode()
,
HashMap
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps