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 JavaBeansTM
has been added to the java.beans package.
Please see java.beans.XMLEncoder
.
Rectangle.Rectangle2D.Rectangle2D.Rectangle2D.Rectangle2D.Rectangle.Rectangle.Rectangle.newx and newy, to this
Rectangle2D. The resulting Rectangle2D
is the smallest Rectangle2D that
contains both the original Rectangle2D and the
specified point.
After adding a point, a call to contains with the
added point as an argument does not necessarily return
true. The contains method does not
return true for points on the right or bottom
edges of a rectangle. Therefore, if the added point falls on
the left or bottom edge of the enlarged rectangle,
contains returns false for that point.
newx
and newy, to this Rectangle. The
resulting Rectangle is
the smallest Rectangle that contains both the
original Rectangle and the specified point.
After adding a point, a call to contains with the
added point as an argument does not necessarily return
true. The contains method does not
return true for points on the right or bottom
edges of a Rectangle. Therefore, if the added point
falls on the right or bottom edge of the enlarged
Rectangle, contains returns
false for that point.
Point to this
Rectangle. The resulting Rectangle
is the smallest Rectangle that contains both the
original Rectangle and the specified
Point.
After adding a Point, a call to contains
with the added Point as an argument does not
necessarily return true. The contains
method does not return true for points on the right
or bottom edges of a Rectangle. Therefore if the added
Point falls on the right or bottom edge of the
enlarged Rectangle, contains returns
false for that Point.
Point2D object pt to this
Rectangle2D.
The resulting Rectangle2D is the smallest
Rectangle2D that contains both the original
Rectangle2D and the specified Point2D.
After adding a point, a call to contains with the
added point as an argument does not necessarily return
true. The contains
method does not return true for points on the right
or bottom edges of a rectangle. Therefore, if the added point falls
on the left or bottom edge of the enlarged rectangle,
contains returns false for that point.
Rectangle to this Rectangle.
The resulting Rectangle is the union of the two
rectangles.Rectangle2D object to this
Rectangle2D. The resulting Rectangle2D
is the union of the two Rectangle2D objects.Rectangle2D.Rectangle2D entirely
contains the specified set of rectangular coordinates.Rectangle contains the
point at the specified location
(x, y).Rectangle entirely contains
the Rectangle
at the specified location (X, Y) with the
specified dimensions (W, H).Rectangle contains the
specified Point.Point2D is inside the boundary
of the Shape.Rectangle entirely contains
the specified Rectangle.Shape entirely contains the
specified Rectangle2D.Rectangle with the
specified Rectangle2D.Rectangle2D object representing the
union of this Rectangle with the specified
Rectangle2D.Rectangle of this Rectangle.
This method is included for completeness, to parallel the
getBounds method of
Component
.
Shape in double
precision.Shape in double
precision.Rectangle in
double precision.FooListeners
upon this caret.
FooListeners 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.
Rectangle.
This method is included for completeness, to parallel the
getLocation method of Component.
Shape in double
precision.Shape in double
precision.Shape in double
precision.Shape in double
precision.Rectangle2D.
The iterator for this class is multi-threaded safe, which means
that this Rectangle2D class guarantees that
modifications to the geometry of this Rectangle2D
object do not affect any iterations of that geometry that
are already in process.Rectangle2D. Since rectangles are already
flat, the flatness parameter is ignored.
The iterator for this class is multi-threaded safe, which means
that this Rectangle2D class guarantees that
modifications to the geometry of this Rectangle2D
object do not affect any iterations of that geometry that
are already in process.Rectangle, represented by
the returned Dimension.
This method is included for completeness, to parallel the
getSize method of Component.
Rectangle in
double precision.Rectangle in
double precision.Rectangle in
double precision.Rectangle both horizontally and vertically.
This method modifies the Rectangle so that it is
h units larger on both the left and right side,
and v units larger at both the top and bottom.
The new Rectangle has (x - h,
y - v) as its top-left corner, a
width of
width + 2h,
and a height of
height + 2v.
If negative values are supplied for h and
v, the size of the Rectangle
decreases accordingly.
The grow method does not check whether the resulting
values of width and height are
non-negative.
Rectangle2D.Rectangle contains the
point at the specified location
(X, Y).Rectangle2D
objects and puts the result into the specified destination
Rectangle2D object. One of the source rectangles
can also be the destination to avoid creating a third Rectangle2D
object, but in this case the original points of this source
rectangle will be overwritten by this method.Rectangle with the
specified Rectangle. Returns a new Rectangle
that represents the intersection of the two rectangles.
If the two rectangles do not intersect, the result will be
an empty rectangle.Rectangle2D
intersects the interior of a specified set of rectangular
coordinates.Rectangle and the specified
Rectangle intersect. Two rectangles intersect if
their intersection is nonempty.Shape intersects the
interior of a specified Rectangle2D.Rectangle2D.Rectangle2D.
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.
Rectangle is empty. A
Rectangle is empty if its width or its height is less
than or equal to zero.MOUSE_DRAGGED events will continue to be
delivered to the component where the drag originated until the
mouse button is released (regardless of whether the mouse position
is within the bounds of the component).
Due to platform-dependent Drag&Drop implementations,
MOUSE_DRAGGED events may not be delivered during a native
Drag&Drop operation.
Rectangle to the specified location.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
Rectangle.
This method computes a binary OR of the appropriate mask values
indicating, for each side of this Rectangle,
whether or not the specified coordinates are on the same side of the
edge as the rest of this Rectangle.Rectangle2D.
This method computes a binary OR of the appropriate mask values
indicating, for each side of this Rectangle2D,
whether or not the specified Point2D is on the same
side of the edge as the rest of this Rectangle2D.Rectangle of this
Rectangle to the specified
x, y, width,
and height.
Rectangle to the specified
width and height.
Rectangle of this
Rectangle to the specified
x, y, width,
and height.
This method is included for completeness, to parallel the
setBounds method of Component.
Rectangle of this Rectangle
to match the specified Rectangle.
This method is included for completeness, to parallel the
setBounds method of Component.
Rectangle2D to the specified rectangular values.Shape to the specified Point2D
and
Dimension2D
, respectively. The framing rectangle is used
by the subclasses of RectangularShape to define
their geometry.Shape to
be the specified Rectangle2D. The framing rectangle is
used by the subclasses of RectangularShape to define
their geometry.Shape
based on the specified center point coordinates and corner point
coordinates. The framing rectangle is used by the subclasses of
RectangularShape to define their geometry.Shape based on a
specified center Point2D and corner
Point2D. The framing rectangle is used by the subclasses
of RectangularShape to define their geometry.Shape
based on the two specified coordinates. The framing rectangle is
used by the subclasses of RectangularShape to define
their geometry.Shape
based on two specified Point2D objects. The framing
rectangle is used by the subclasses of RectangularShape
to define their geometry.Rectangle to the specified location.
This method is included for completeness, to parallel the
setLocation method of Component.
Rectangle to the specified location.
This method is included for completeness, to parallel the
setLocation method of Component.
Rectangle to the specified
x, y, width,
and height.
This method is included for completeness, to parallel the
setBounds method of Component.Rectangle2D to be the same as the specified
Rectangle2D.Rectangle to match the
specified Dimension.
This method is included for completeness, to parallel the
setSize method of Component.
Rectangle to the specified
width and height.
This method is included for completeness, to parallel the
setSize method of Component.
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.
Rectangle the indicated distance,
to the right along the x coordinate axis, and
downward along the y coordinate axis.Rectangle with the
specified Rectangle. Returns a new
Rectangle that
represents the union of the two rectanglesRectangle2D objects
and puts the result into the specified destination
Rectangle2D object. One of the source rectangles
can also be the destination to avoid creating a third Rectangle2D
object, but in this case the original points of this source
rectangle will be overwritten by this method.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.