Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.swing.text
Class DefaultCaret

    java.lang.Object
      |
      +--java.awt.Rectangle
            |
            +--javax.swing.text.DefaultCaret

Direct Known Subclasses:
  BasicTextUI.BasicCaret

public class DefaultCaret
extends java.awt.Rectangle
implements Caret, java.awt.event.FocusListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener

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 thread as a result of some mouse or keyboard event. Updates can also occur from some other thread mutating the document. There is a property `AsynchronousMovement` that determines if the caret will move on asynchronous updates. The default behavior is to not update on asynchronous updates. If asynchronous updates are allowed, the update thread will fire the caret position change to listeners asynchronously. 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).

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. A future release of Swing will provide support for long term persistence.

See Also:
  `Caret`, Serialized Form

Field Summary
`protected ChangeEvent` | `changeEvent` The change event for the model.
`protected EventListenerList` | `listenerList` The event listener list.

Fields inherited from class java.awt.Rectangle
`height, width, x, y`

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(java.awt.Rectangle nloc)` Scrolls the associated view (if necessary) to make the caret visible.
`protected void` | `damage(java.awt.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.
`protected void` | `fireStateChanged()` Notifies all listeners that have registered interest for notification on this event type.
`void` | `focusGained(java.awt.event.FocusEvent e)` Called when the component containing the caret gains focus.
`void` | `focusLost(java.awt.event.FocusEvent e)` Called when the component containing the caret loses focus.
`int` | `getBlinkRate()` Gets the caret blink rate.
`protected JTextComponent` | `getComponent()` Gets the text editor component that this caret is is bound to.
`int` | `getDot()` Fetches the current position of the caret.
`java.awt.Point` | `getMagicCaretPosition()` Gets the saved caret position.
`int` | `getMark()` Fetches the current position of the mark.
`protected Highlighter.HighlightPainter` | `getSelectionPainter()` Gets the painter for the Highlighter.
`void` | `install(JTextComponent c)` Called when the UI is being installed into the interface of a JTextComponent.
`boolean` | `isSelectionVisible()` Checks whether the current selection is visible.
`boolean` | `isVisible()` Determines if the caret is currently visible.
`void` | `mouseClicked(java.awt.event.MouseEvent e)` Called when the mouse is clicked.
`void` | `mouseDragged(java.awt.event.MouseEvent e)` Moves the caret position according to the mouse pointer's current location.
`void` | `mouseEntered(java.awt.event.MouseEvent e)` Called when the mouse enters a region.
`void` | `mouseExited(java.awt.event.MouseEvent e)` Called when the mouse exits a region.
`void` | `mouseMoved(java.awt.event.MouseEvent e)` Called when the mouse is moved.
`void` | `mousePressed(java.awt.event.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(java.awt.event.MouseEvent e)` Called when the mouse is released.
`protected void` | `moveCaret(java.awt.event.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 some other position.
`void` | `paint(java.awt.Graphics g)` Renders the caret as a vertical line.
`protected void` | `positionCaret(java.awt.event.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 some position.
`void` | `setMagicCaretPosition(java.awt.Point p)` Saves the current caret position.
`void` | `setSelectionVisible(boolean vis)` Changes the selection visibility.
`void` | `setVisible(boolean e)` Sets the caret visibility, and repaints the caret.
`java.lang.String` | `toString()`

Methods inherited from class java.awt.Rectangle
`add, add, add, contains, contains, equals, getBounds, getLocation, getSize, grow, hashCode, inside, intersection, intersects, isEmpty, move, reshape, resize, setBounds, setBounds, setLocation, setLocation, setSize, setSize, translate, union`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### listenerList

    protected EventListenerList listenerList

  The event listener list.

### changeEvent

    protected transient ChangeEvent changeEvent

  The change event for the model. Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

Constructor Detail

### DefaultCaret

    public DefaultCaret()

  Constructs a default caret.

Method Detail

### getComponent

    protected final JTextComponent getComponent()

  Gets the text editor component that this caret is is bound to.
  Returns:
    the component

### repaint

    protected final void repaint()

  Cause the caret to be painted. The repaint area is the bounding box of the caret (i.e. the caret rectangle or this).

  This method is thread safe, although most Swing methods are not. Please see Threads and Swing for more information.

### damage

    protected void damage(java.awt.Rectangle r)

  Damages the area surrounding the caret to cause it to be repainted in a new location. If paint() is reimplemented, this method should also be reimplemented. This method should update the caret bounds (x, y, width, and height).
  Parameters:
    `r` - the current location of the caret
  See Also:
    `paint(java.awt.Graphics)`

### adjustVisibility

    protected void adjustVisibility(java.awt.Rectangle nloc)

  Scrolls the associated view (if necessary) to make the caret visible. Since how this should be done is somewhat of a policy, this method can be reimplemented to change the behavior. By default the scrollRectToVisible method is called on the associated component.
  Parameters:
    `nloc` - the new position to scroll to

### getSelectionPainter

    protected Highlighter.HighlightPainter getSelectionPainter()

  Gets the painter for the Highlighter.
  Returns:
    the painter

### positionCaret

    protected void positionCaret(java.awt.event.MouseEvent e)

  Tries to set the position of the caret from the coordinates of a mouse event, using viewToModel().
  Parameters:
    `e` - the mouse event

### moveCaret

    protected void moveCaret(java.awt.event.MouseEvent e)

  Tries to move the position of the caret from the coordinates of a mouse event, using viewToModel(). This will cause a selection if the dot and mark are different.
  Parameters:
    `e` - the mouse event

### focusGained

    public void focusGained(java.awt.event.FocusEvent e)

  Called when the component containing the caret gains focus. This is implemented to set the caret to visible if the component is editable.
  Specified by:
    focusGained in interface java.awt.event.FocusListener
  Parameters:
    `e` - the focus event
  See Also:
    `FocusListener.focusGained(java.awt.event.FocusEvent)`

### focusLost

    public void focusLost(java.awt.event.FocusEvent e)

  Called when the component containing the caret loses focus. This is implemented to set the caret to visibility to false.
  Specified by:
    focusLost in interface java.awt.event.FocusListener
  Parameters:
    `e` - the focus event
  See Also:
    `FocusListener.focusLost(java.awt.event.FocusEvent)`

### mouseClicked

    public void mouseClicked(java.awt.event.MouseEvent e)

  Called when the mouse is clicked. If the click was generated from button1, a double click selects a word, and a triple click the current line.
  Specified by:
    mouseClicked in interface java.awt.event.MouseListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseListener.mouseClicked(java.awt.event.MouseEvent)`

### mousePressed

    public void mousePressed(java.awt.event.MouseEvent e)

  If button 1 is pressed, this is implemented to request focus on the associated text component, and to set the caret position. If the component is not enabled, there will be no request for focus.
  Specified by:
    mousePressed in interface java.awt.event.MouseListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseListener.mousePressed(java.awt.event.MouseEvent)`

### mouseReleased

    public void mouseReleased(java.awt.event.MouseEvent e)

  Called when the mouse is released.
  Specified by:
    mouseReleased in interface java.awt.event.MouseListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseListener.mouseReleased(java.awt.event.MouseEvent)`

### mouseEntered

    public void mouseEntered(java.awt.event.MouseEvent e)

  Called when the mouse enters a region.
  Specified by:
    mouseEntered in interface java.awt.event.MouseListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseListener.mouseEntered(java.awt.event.MouseEvent)`

### mouseExited

    public void mouseExited(java.awt.event.MouseEvent e)

  Called when the mouse exits a region.
  Specified by:
    mouseExited in interface java.awt.event.MouseListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseListener.mouseExited(java.awt.event.MouseEvent)`

### mouseDragged

    public void mouseDragged(java.awt.event.MouseEvent e)

  Moves the caret position according to the mouse pointer's current location. This effectively extends the selection.
  Specified by:
    mouseDragged in interface java.awt.event.MouseMotionListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseMotionListener.mouseDragged(java.awt.event.MouseEvent)`

### mouseMoved

    public void mouseMoved(java.awt.event.MouseEvent e)

  Called when the mouse is moved.
  Specified by:
    mouseMoved in interface java.awt.event.MouseMotionListener
  Parameters:
    `e` - the mouse event
  See Also:
    `MouseMotionListener.mouseMoved(java.awt.event.MouseEvent)`

### paint

    public void paint(java.awt.Graphics g)

  Renders the caret as a vertical line. If this is reimplemented the damage method should also be reimplemented as it assumes the shape of the caret is a vertical line. Sets the caret color to the value returned by getCaretColor().

  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).

  Specified by:
    paint in interface Caret
  Parameters:
    `g` - the graphics context
  See Also:
    `damage(java.awt.Rectangle)`

### install

    public void install(JTextComponent c)

  Called when the UI is being installed into the interface of a JTextComponent. This can be used to gain access to the model that is being navigated by the implementation of this interface. Sets the dot and mark to 0, and establishes document, property change, focus, mouse, and mouse motion listeners.
  Specified by:
    install in interface Caret
  Parameters:
    `c` - the component
  See Also:
    `Caret.install(javax.swing.text.JTextComponent)`

### deinstall

    public void deinstall(JTextComponent c)

  Called when the UI is being removed from the interface of a JTextComponent. This is used to unregister any listeners that were attached.
  Specified by:
    deinstall in interface Caret
  Parameters:
    `c` - the component
  See Also:
    `Caret.deinstall(javax.swing.text.JTextComponent)`

### addChangeListener

    public void addChangeListener(ChangeListener l)

  Adds a listener to track whenever the caret position has been changed.
  Specified by:
    addChangeListener in interface Caret
  Parameters:
    `l` - the listener
  See Also:
    `Caret.addChangeListener(javax.swing.event.ChangeListener)`

### removeChangeListener

    public void removeChangeListener(ChangeListener l)

  Removes a listener that was tracking caret position changes.
  Specified by:
    removeChangeListener in interface Caret
  Parameters:
    `l` - the listener
  See Also:
    `Caret.removeChangeListener(javax.swing.event.ChangeListener)`

### fireStateChanged

    protected void fireStateChanged()

  Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed last to first.
  See Also:
    `EventListenerList`

### setSelectionVisible

    public void setSelectionVisible(boolean vis)

  Changes the selection visibility.
  Specified by:
    setSelectionVisible in interface Caret
  Parameters:
    `vis` - the new visibility

### isSelectionVisible

    public boolean isSelectionVisible()

  Checks whether the current selection is visible.
  Specified by:
    isSelectionVisible in interface Caret
  Returns:
    true if the selection is visible

### isVisible

    public boolean isVisible()

  Determines if the caret is currently visible.
  Specified by:
    isVisible in interface Caret
  Returns:
    true if visible else false
  See Also:
    `Caret.isVisible()`

### setVisible

    public void setVisible(boolean e)

  Sets the caret visibility, and repaints the caret.
  Specified by:
    setVisible in interface Caret
  Parameters:
    `e` - the visibility specifier
  See Also:
    `Caret.setVisible(boolean)`

### setBlinkRate

    public void setBlinkRate(int rate)

  Sets the caret blink rate.
  Specified by:
    setBlinkRate in interface Caret
  Parameters:
    `rate` - the rate in milliseconds, 0 to stop blinking
  See Also:
    `Caret.setBlinkRate(int)`

### getBlinkRate

    public int getBlinkRate()

  Gets the caret blink rate.
  Specified by:
    getBlinkRate in interface Caret
  See Also:
    `Caret.getBlinkRate()`

### getDot

    public int getDot()

  Fetches the current position of the caret.
  Specified by:
    getDot in interface Caret
  Returns:
    the position >= 0
  See Also:
    `Caret.getDot()`

### getMark

    public int getMark()

  Fetches the current position of the mark. If there is a selection, the dot and mark will not be the same.
  Specified by:
    getMark in interface Caret
  Returns:
    the position >= 0
  See Also:
    `Caret.getMark()`

### setDot

    public void setDot(int dot)

  Sets the caret position and mark to some position. This implicitly sets the selection range to zero.
  Specified by:
    setDot in interface Caret
  Parameters:
    `dot` - the position >= 0
  See Also:
    `Caret.setDot(int)`

### moveDot

    public void moveDot(int dot)

  Moves the caret position to some other position.
  Specified by:
    moveDot in interface Caret
  Parameters:
    `dot` - the position >= 0
  See Also:
    `Caret.moveDot(int)`

### setMagicCaretPosition

    public void setMagicCaretPosition(java.awt.Point p)

  Saves the current caret position. This is used when caret up/down actions occur, moving between lines that have uneven end positions.
  Specified by:
    setMagicCaretPosition in interface Caret
  Parameters:
    `p` - the position
  See Also:
    `getMagicCaretPosition()`, `UpAction`, `DownAction`

### getMagicCaretPosition

    public java.awt.Point getMagicCaretPosition()

  Gets the saved caret position.
  Specified by:
    getMagicCaretPosition in interface Caret
  Returns:
    the position see #setMagicCaretPosition

### toString

    public java.lang.String toString()

  Overrides:
    toString in class java.awt.Rectangle

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.