javax.swing.text
类 DefaultCaret

java.lang.Object
  java.awt.geom.RectangularShape
      java.awt.geom.Rectangle2D
          java.awt.Rectangle
              javax.swing.text.DefaultCaret

所有已实现的接口：

FocusListener, MouseListener, MouseMotionListener, Shape, Serializable, Cloneable, EventListener, Caret

直接已知子类：

BasicTextUI.BasicCaret

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

插入符的默认实现。插入符以垂直线形式呈现，颜色由相关的 JTextComponent 的 CaretColor 属性指定。它可以按 BlinkRate 属性中指定的速率闪烁。

此实现需要两个异步通知源。计时器线程为异步触发，这使得插入符只需重绘最新的边界框。当修改文档时，插入符还跟踪更改。通常这发生在某些鼠标或键盘事件引起的事件调度线程中。同步和异步文档更新中的插入符的行为是由 UpdatePolicy 属性控制的。重绘新插入符位置在任何情况下都发生在事件线程上，因为只有在事件线程上对 modelToView 的调用才是安全的。

插入符充当它所安装到的文本组件上的鼠标和焦点侦听器，并根据这些事件定义插入符的语义。侦听器方法可重新实现以更改其语义。默认情况下，第一个鼠标按钮将用于设置焦点和插入符位置。用第一个鼠标按钮拖动鼠标指针将在模型中划出一个连续选定。如果关联的文本组件为可编辑的，此插入符在获得焦点时将为可见，在失去焦点时为不可见。

关联的文本组件的 Highlighter 边界默认用于呈现选定。通过提供高亮显示所用的 painter，可定制选定的外观。默认情况下，painter 用于需要用关联文本组件的 SelectionColor 属性中指定的纯色呈现的情况。通过重新实现 getSelectionHighlighter 方法，可以很容易地更改此方法。

通过重新实现该 paint 方法，可获得定制的插入符外观。如果 paint 方法已更改，damage 方法也应重新实现，这样可重新绘制需要的区域以便呈现插入符。插入符扩展了 Rectangle 类，它用于保持记录上次呈现插入符的位置的边界框。这有助于插入符以线程安全的方式重绘，因为在模型更新和视图修复期间移动插入符而不调用 modelToView 是不稳定的（即无法保证传递到 DocumentListeners 的顺序）。

当插入符位置改变时，此变幻的插入符位置将设置为 null。使用计时器确定新的位置（在插入符改变后）。计时器触发后，如果变幻的插入符位置仍为 null，它将重置为当前的插入符位置。任何更改插入符位置和希望变幻的插入符位置保持不变的操作都必须记住变幻的插入符位置和更改光标，然后将变幻的插入符位置设置为原始值。这样做的好处是，只有希望变幻的插入符位置保持不变的操作（例如打开/向下）需要知道它的值。

警告：此类的序列化对象与以后的 Swing 版本不兼容。当前序列化支持适用于短期存储，或适用于在运行相同 Swing 版本的应用程序之间进行 RMI（Remote Method Invocation，远程方法调用）。从 1.4 版本开始，已在 java.beans 包中添加了支持所有 JavaBeans^TM 长期存储的功能。请参见 XMLEncoder。

另请参见：

Caret

UPDATE_WHEN_ON_EDT

public static final int UPDATE_WHEN_ON_EDT

指示只有在事件调度线程中执行文档更改时，才更新插入符位置。

从以下版本开始：

1.5

另请参见：

setUpdatePolicy(int), getUpdatePolicy(), 常量字段值

NEVER_UPDATE

public static final int NEVER_UPDATE

指示无论文档有任何更新，插入符都应在文档中保持同一绝对位置，由于删除使文档长度小于当前插入符位置除外。这种情况下，插入符位置将调整到文档的结尾。

从以下版本开始：

1.5

另请参见：

setUpdatePolicy(int), getUpdatePolicy(), 常量字段值

ALWAYS_UPDATE

public static final int ALWAYS_UPDATE

指示无论文档更新是否是在事件调度线程中执行，始终根据文档更改更新插入符位置。

从以下版本开始：

1.5

另请参见：

setUpdatePolicy(int), getUpdatePolicy(), 常量字段值

listenerList

protected EventListenerList listenerList

事件侦听器列表。

changeEvent

protected transient ChangeEvent changeEvent

此模型的更改事件。由于事件的唯一状态（只读）为源属性，所以每个模型实例只需要一个 ChangeEvent。这里生成的事件源总是 "this"。

DefaultCaret

public DefaultCaret()

构造默认的插入符。

setUpdatePolicy

public void setUpdatePolicy(int policy)

设置文档更新时的插入符移动策略。通常，当在插入符位置之前或当前位置插入时，以及在插入符位置之前删除时，插入符会更新其在文档中的绝对位置。这里的“绝对位置”指的是相对于文档开头的位置。例如，在一个可编辑的文本组件中输入一个字符时，它将插入到插入符位置，而插入符由于此插入将移动到文档中下一个绝对位置，如果输入的是 BACKSPACE，插入符的绝对位置将减小，因为在它之前删除了一个字符。有时候，关闭插入符位置更新很有用，这样无论文档怎么更新，插入符都将保持在文档中同一绝对位置。

允许以下更新策略：

• NEVER_UPDATE：无论文档怎样更新，插入符在文档中都位于同一绝对位置，除非由于删除使文档长度小于当前插入符位置。这种情况下，插入符位置将被调整到文档的结尾。使用此策略时，插入符不会试图在滚动关联的视图时保持可见。
• ALWAYS_UPDATE：插入符始终跟踪文档更改。对于一般的更改，如果在插入符位置之前或当前位置插入，则增加它的位置，如果在当前位置之前删除，则减小它的位置。对于撤消/恢复更新，它总是移动到更新发生的位置。插入符总是试图通过调用 adjustVisibility 方法保持可见。
• UPDATE_WHEN_ON_EDT：如果文档更新在事件调度线程上执行，则与 ALWAYS_UPDATE 动作类似；如果文档更新在其它线程上执行，则与 NEVER_UPDATE 类似。

默认属性值为 UPDATE_WHEN_ON_EDT。

参数：

policy - 它是以下值之一：UPDATE_WHEN_ON_EDT、NEVER_UPDATE、ALWAYS_UPDATE

抛出：

IllegalArgumentException - 如果传入无效的值

从以下版本开始：

1.5

另请参见：

getUpdatePolicy(), adjustVisibility(java.awt.Rectangle), UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE

getUpdatePolicy

public int getUpdatePolicy()

获取文档更新时的插入符移动策略。

返回：

以下值之一：UPDATE_WHEN_ON_EDT、NEVER_UPDATE、ALWAYS_UPDATE

从以下版本开始：

1.5

另请参见：

setUpdatePolicy(int), UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE

getComponent

protected final JTextComponent getComponent()

获取此插入符所绑定的文本编辑器组件。

返回：

组件

repaint

protected final void repaint()

使得重绘插入符。重绘区域为插入符的边界框（即插入符矩形或 this）。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。

damage

protected void damage(Rectangle r)

毁坏围绕插入符的区域以使该区域在新的位置重绘。如果重新实现 paint()，此方法也应重新实现。此方法应更新插入符边界（x、y、width 和 height）。

参数：

r - 插入符的当前位置

另请参见：

paint(java.awt.Graphics)

adjustVisibility

protected void adjustVisibility(Rectangle nloc)

滚动关联的视图（如果有）以使插入符可见。究竟应该如何动作在某种程度上是一个策略的问题，此方法可重新实现以更改此行为。默认情况下，scrollRectToVisible 方法在关联的组件中调用。

参数：

nloc - 要滚动到的新位置

getSelectionPainter

protected Highlighter.HighlightPainter getSelectionPainter()

获取此 Highlighter 的 painter。

返回：

painter

positionCaret

protected void positionCaret(MouseEvent e)

试图使用 viewToModel() 从鼠标事件的坐标设置插入符的位置。

参数：

e - 鼠标事件

moveCaret

protected void moveCaret(MouseEvent e)

试图使用 viewToModel() 从鼠标事件的坐标移动插入符的位置。如果点与标记不同，这将产生一个选定。

参数：

e - 鼠标事件

focusGained

public void focusGained(FocusEvent e)

在包含插入符的组件获得焦点时调用。如果组件为可编辑，实现此方法可将插入符设置为可见。

指定者：

接口 FocusListener 中的 focusGained

参数：

e - 鼠标事件

另请参见：

FocusListener.focusGained(java.awt.event.FocusEvent)

focusLost

public void focusLost(FocusEvent e)

在包含插入符的组件失去焦点时调用。实现此方法可将插入符的可见性设置为 false。

指定者：

接口 FocusListener 中的 focusLost

参数：

e - 鼠标事件

另请参见：

FocusListener.focusLost(java.awt.event.FocusEvent)

mouseClicked

public void mouseClicked(MouseEvent e)

单击鼠标时调用。如果单击是由 button1 生成的，则双击选中一个字，三击选中当前行。

指定者：

接口 MouseListener 中的 mouseClicked

参数：

e - 鼠标事件

另请参见：

MouseListener.mouseClicked(java.awt.event.MouseEvent)

mousePressed

public void mousePressed(MouseEvent e)

如果按下 button 1，实现它可请求将焦点置于关联的文本组件上，并设置插入符位置。如果按住 shift 键，插入符将移动，潜在导致一个选定，否则插入符位置将被设置为新位置。如果该组件未启用，则不会有任何焦点请求。

指定者：

接口 MouseListener 中的 mousePressed

参数：

e - 鼠标事件

另请参见：

MouseListener.mousePressed(java.awt.event.MouseEvent)

mouseReleased

public void mouseReleased(MouseEvent e)

释放鼠标时调用。

指定者：

接口 MouseListener 中的 mouseReleased

参数：

e - 鼠标事件

另请参见：

MouseListener.mouseReleased(java.awt.event.MouseEvent)

mouseEntered

public void mouseEntered(MouseEvent e)

鼠标进入某个区域时调用。

指定者：

接口 MouseListener 中的 mouseEntered

参数：

e - 鼠标事件

另请参见：

MouseListener.mouseEntered(java.awt.event.MouseEvent)

mouseExited

public void mouseExited(MouseEvent e)

鼠标退出某个区域时调用。

指定者：

接口 MouseListener 中的 mouseExited

参数：

e - 鼠标事件

另请参见：

MouseListener.mouseExited(java.awt.event.MouseEvent)

mouseDragged

public void mouseDragged(MouseEvent e)

根据鼠标指针当前位置移动插入符位置。这有效地扩展了选定。默认情况下，只有鼠标按键 1 才能完成这一操作。

指定者：

接口 MouseMotionListener 中的 mouseDragged

参数：

e - 鼠标事件

另请参见：

MouseMotionListener.mouseDragged(java.awt.event.MouseEvent)

mouseMoved

public void mouseMoved(MouseEvent e)

移动鼠标时调用。

指定者：

接口 MouseMotionListener 中的 mouseMoved

参数：

e - 鼠标事件

另请参见：

MouseMotionListener.mouseMoved(java.awt.event.MouseEvent)

paint

public void paint(Graphics g)

将插入符作为垂直线呈现。如果重新实现此方法，则 damage 方法也应重新实现，因为它假定插入符的形状为垂直线。将插入符颜色设置为 getCaretColor() 返回的值。

如果关联文档中有多个文本方向，将呈现一个指示插入符偏移的标志。只有当关联文档为 AbstractDocument 的子类并且在双向元素结构中有多个双向级别时（即文本关联了多个方向），才会发生这样的情况。

指定者：

接口 Caret 中的 paint

参数：

g - 图形上下文

另请参见：

damage(java.awt.Rectangle)

install

public void install(JTextComponent c)

当 UI 装入一个 JTextComponent 的接口时调用。使用此方法可获得对由此接口的实现导航的模型的访问。将点和标记设置为 0，并建立文档、属性更改、焦点、鼠标及鼠标动作侦听器。

指定者：

接口 Caret 中的 install

参数：

c - 组件

另请参见：

Caret.install(javax.swing.text.JTextComponent)

deinstall

public void deinstall(JTextComponent c)

当 UI 从一个 JTextComponent 的接口移除时调用。这可用于取消对任何所关联侦听器的注册。

指定者：

接口 Caret 中的 deinstall

参数：

c - 组件

另请参见：

Caret.deinstall(javax.swing.text.JTextComponent)

addChangeListener

public void addChangeListener(ChangeListener l)

添加一个侦听器，以便对插入符位置改变进行跟踪。

指定者：

接口 Caret 中的 addChangeListener

参数：

l - 侦听器

另请参见：

Caret.addChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)

移除跟踪位置更改的侦听器。

指定者：

接口 Caret 中的 removeChangeListener

参数：

l - 侦听器

另请参见：

Caret.removeChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()

返回此插入符上所有已注册的更改侦听器组成的数组。

返回：

此插入符的所有 ChangeListener， 如果当前未注册任何改侦听器，则返回一个空数组

从以下版本开始：

1.4

另请参见：

addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()

通知所有需要此事件类型的通知的已注册侦听器。使用传入此触发方法的参数延后创建事件实例。从后向前处理侦听器列表。

另请参见：

EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)

返回目前已在此插入符上注册为 FooListener 的所有对象组成的数组。FooListener 是用 addFooListener 方法注册的。

可以使用 class 字面值来指定 listenerType 参数，如 FooListener.class。例如，可以使用以下代码查询 DefaultCaret c 以获得其更改侦听器：

ChangeListener[] cls = (ChangeListener[])(c.getListeners(ChangeListener.class));

如果不存在这样的侦听器，则此方法将返回一个空数组。

参数：

listenerType - 所请求的侦听器类型；此参数应该指定一个从 java.util.EventListener 继承的接口

返回：

返回一个在此组件上作为 FooListener 注册的所有对象的数组，如果尚未添加这样的侦听器，则返回一个空数组

抛出：

ClassCastException - 如果 listenerType 未指定一个实现 java.util.EventListener 的类或接口

从以下版本开始：

1.3

另请参见：

getChangeListeners()

setSelectionVisible

public void setSelectionVisible(boolean vis)

更改选定的可见性。

指定者：

接口 Caret 中的 setSelectionVisible

参数：

vis - 新可见性

isSelectionVisible

public boolean isSelectionVisible()

检查当前选定是否可见。

指定者：

接口 Caret 中的 isSelectionVisible

返回：

如果选定为可见，则返回 true

isActive

public boolean isActive()

确定插入符当前是否处于激活状态。

此方法返回 Caret 当前是否处于闪烁状态。它不提供有关当前闪烁为打开或关闭的信息。要确定插入符当前是否绘制，请使用 isVisible 方法。

返回：

如果处于激活状态，则返回 true；否则返回 false

从以下版本开始：

1.5

另请参见：

isVisible()

isVisible

public boolean isVisible()

指示插入符当前是否可见。由于插入符闪烁打开和关闭，它的返回值将在 true 和 false 之间改变。当绘制插入符时，返回 true；当不绘制插入符时，返回 false。isActive 指示插入符是否处于闪烁状态，它可能为可见，而 isVisible 指示插入符是否确实为可见。

希望呈现不同的闪烁插入符的子类应重写 paint，并只在此方法返回 true 时才绘制插入符。

指定者：

接口 Caret 中的 isVisible

返回：

如果可见，则返回 true；否则返回 false

另请参见：

Caret.isVisible(), isActive()

setVisible

public void setVisible(boolean e)

设置插入符可见性，并重绘插入符。理解此方法、isVisible 以及 isActive 三者之间的关系非常重要。使用 true 值调用此方法可激活插入符闪烁。将它设置为 false 可彻底关闭闪烁。要确定闪烁是否激活，应调用 isActive。从实际效果来看，isActive 相当于它的 "getter" 方法，isVisible 可用于获取插入符的当前可见状态，即当前是否绘制的状态。此状态将随插入符的闪烁打开和关闭而更改。

下面的列表显示了调用此方法后 isActive 和 isVisible 可能的返回值：

setVisible(true):

• isActive():true
• isVisible():true 或 false 取决于插入符闪烁为打开还是关闭

setVisible(false):

• isActive():false
• isVisible():false

指定者：

接口 Caret 中的 setVisible

参数：

e - 可见性指示符

另请参见：

isActive(), Caret.setVisible(boolean)

setBlinkRate

public void setBlinkRate(int rate)

设置插入符闪烁率。

指定者：

接口 Caret 中的 setBlinkRate

参数：

rate - 闪烁率，以毫秒为单位，0 为停止闪烁

另请参见：

Caret.setBlinkRate(int)

getBlinkRate

public int getBlinkRate()

获取插入符闪烁率。

指定者：

接口 Caret 中的 getBlinkRate

返回：

延迟，以毫秒为单位。如果为 0，则插入符不闪烁。

另请参见：

Caret.getBlinkRate()

getDot

public int getDot()

获取插入符的当前位置。

指定者：

接口 Caret 中的 getDot

返回：

位置，该位置 >= 0

另请参见：

Caret.getDot()

getMark

public int getMark()

获取标记的当前位置。如果有选定，点和标记将不同。

指定者：

接口 Caret 中的 getMark

返回：

位置，该位置 >= 0

另请参见：

Caret.getMark()

setDot

public void setDot(int dot)

将插入符位置和标记设置为指定位置，存在向前偏差。此方法将选择范围隐式地设置为 0。

指定者：

接口 Caret 中的 setDot

参数：

dot - 位置，该位置 >= 0

另请参见：

setDot(int, Position.Bias), Caret.setDot(int)

moveDot

public void moveDot(int dot)

将插入符位置移动到指定位置，存在向前偏差。

指定者：

接口 Caret 中的 moveDot

参数：

dot - 位置，该位置 >= 0

另请参见：

moveDot(int, javax.swing.text.Position.Bias), Caret.moveDot(int)

moveDot

public void moveDot(int dot,
                    Position.Bias dotBias)

将插入符位置移动到指定位置，存在指定偏差。

参数：

dot - >= 0 的位置

dotBias - 此位置的偏差，不为 null

抛出：

IllegalArgumentException - 如果偏差为 null

从以下版本开始：

1.6

另请参见：

Caret.moveDot(int)

setDot

public void setDot(int dot,
                   Position.Bias dotBias)

将插入符位置和标记设置为指定位置，存在指定偏差。此方法将选择范围隐式地设置为 0。

参数：

dot - >= 0 的位置

dotBias - 此位置的偏差，不为 null

抛出：

IllegalArgumentException - 如果偏差为 null

从以下版本开始：

1.6

另请参见：

Caret.setDot(int)

getDotBias

public Position.Bias getDotBias()

返回插入符位置的偏差。

返回：

插入符位置的偏差

从以下版本开始：

1.6

getMarkBias

public Position.Bias getMarkBias()

返回标记的偏差。

返回：

标记的偏差

从以下版本开始：

1.6

setMagicCaretPosition

public void setMagicCaretPosition(Point p)

保存当前插入符位置。这在插入符有向上/向下动作时使用，方便在不均匀结束位置的行间移动。

指定者：

接口 Caret 中的 setMagicCaretPosition

参数：

p - 位置

另请参见：

getMagicCaretPosition()

getMagicCaretPosition

public Point getMagicCaretPosition()

获取保存的插入符位置。

指定者：

接口 Caret 中的 getMagicCaretPosition

返回：

位置 see #setMagicCaretPosition

另请参见：

Caret.setMagicCaretPosition(java.awt.Point)

equals

public boolean equals(Object obj)

将此对象与指定的对象进行比较。比较矩形的超类行为是不需要的，所以这将更改为 Object 行为。

覆盖：

类 Rectangle 中的 equals

参数：

obj - 要与此字体比较的对象

返回：

如果对象相同，则返回 true；否则，返回 false

另请参见：

Object.hashCode(), Hashtable

toString

public String toString()

从类 Rectangle 复制的描述

返回表示此 Rectangle 及其值的 String。

覆盖：

类 Rectangle 中的 toString

返回：

表示此 Rectangle 对象的坐标和大小值的 String。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。