JavaTM 2 Platform
Standard Ed. 5.0

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。从 1.4 版本开始,已在 java.beans 包中添加了支持所有 JavaBeansTM 长期存储的功能。请参见 XMLEncoder

另请参见:
Caret

嵌套类摘要
 
从类 java.awt.geom.Rectangle2D 继承的嵌套类/接口
Rectangle2D.Double, Rectangle2D.Float
 
字段摘要
static int ALWAYS_UPDATE
          指示无论文档更新是否是在事件调度线程中执行,始终根据文档更改更新插入符位置。
protected  ChangeEvent changeEvent
          此模型的更改事件。
protected  EventListenerList listenerList
          事件侦听器列表。
static int NEVER_UPDATE
          指示无论文档有任何更新,插入符都应在文档中保持同一绝对位置,由于删除使文档长度小于当前插入符位置除外。
static int UPDATE_WHEN_ON_EDT
          指示只有在事件调度线程中执行文档更改时,才更新插入符位置。
 
从类 java.awt.Rectangle 继承的字段
height, width, x, y
 
从类 java.awt.geom.Rectangle2D 继承的字段
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
 
构造方法摘要
DefaultCaret()
          构造默认的插入符。
 
方法摘要
 void addChangeListener(ChangeListener l)
          添加一个侦听器,以便对插入符位置改变进行跟踪。
protected  void adjustVisibility(Rectangle nloc)
          滚动关联的视图(如果有)以使插入符可见。
protected  void damage(Rectangle r)
          毁坏围绕插入符的区域以使该区域在新的位置重绘。
 void deinstall(JTextComponent c)
          当 UI 从一个 JTextComponent 的接口移除时调用。
 boolean equals(Object obj)
          将此对象与指定的对象进行比较。
protected  void fireStateChanged()
          通知所有对此事件类型的通知感兴趣的已注册侦听器。
 void focusGained(FocusEvent e)
          在包含插入符的组件获得焦点时调用。
 void focusLost(FocusEvent e)
          在包含插入符的组件失去焦点时调用。
 int getBlinkRate()
          获得插入符闪烁率。
 ChangeListener[] getChangeListeners()
          返回此插入符上所有已注册的更改侦听器组成的数组。
protected  JTextComponent getComponent()
          获得此插入符所绑定的文本编辑器组件。
 int getDot()
          获取插入符的当前位置。
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
          返回目前已在此插入符上注册为 FooListener 的所有对象组成的数组。
 Point getMagicCaretPosition()
          获得保存的插入符位置。
 int getMark()
          获取标记的当前位置。
protected  Highlighter.HighlightPainter getSelectionPainter()
          获得此 Highlighter 的 painter。
 int getUpdatePolicy()
          获得文档更新时的插入符移动策略。
 void install(JTextComponent c)
          当 UI 装入一个 JTextComponent 的接口时调用。
 boolean isActive()
          确定插入符当前是否处于激活状态。
 boolean isSelectionVisible()
          检查当前选定是否可见。
 boolean isVisible()
          指示插入符当前是否可见。
 void mouseClicked(MouseEvent e)
          单击鼠标时调用。
 void mouseDragged(MouseEvent e)
          根据鼠标指针当前位置移动插入符位置。
 void mouseEntered(MouseEvent e)
          鼠标进入某个区域时调用。
 void mouseExited(MouseEvent e)
          鼠标退出某个区域时调用。
 void mouseMoved(MouseEvent e)
          移动鼠标时调用。
 void mousePressed(MouseEvent e)
          如果按下 button 1,实现它可请求将焦点置于关联的文本组件上,并设置插入符位置。
 void mouseReleased(MouseEvent e)
          释放鼠标时调用。
protected  void moveCaret(MouseEvent e)
          试图使用 viewToModel() 从鼠标事件的坐标移动插入符的位置。
 void moveDot(int dot)
          将插入符位置移动到某个其他位置。
 void paint(Graphics g)
          将插入符作为垂直线呈现。
protected  void positionCaret(MouseEvent e)
          试图使用 viewToModel() 从鼠标事件的坐标设置插入符的位置。
 void removeChangeListener(ChangeListener l)
          移除跟踪位置更改的侦听器。
protected  void repaint()
          使得重绘插入符。
 void setBlinkRate(int rate)
          设置插入符闪烁率。
 void setDot(int dot)
          将插入符位置和标记设置为某个位置。
 void setMagicCaretPosition(Point p)
          保存当前插入符位置。
 void setSelectionVisible(boolean vis)
          更改选定的可见性。
 void setUpdatePolicy(int policy)
          设置文档更新时的插入符移动策略。
 void setVisible(boolean e)
          设置插入符可见性,并重绘插入符。
 String toString()
          返回表示此 Rectangle 及其值的 String
 
从类 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
 
从类 java.awt.geom.Rectangle2D 继承的方法
add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union
 
从类 java.awt.geom.RectangularShape 继承的方法
clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait
 
从接口 java.awt.Shape 继承的方法
contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects
 

字段详细信息

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,插入符的绝对位置将减小,因为在它之前删除了一个字符。有时候,关闭插入符位置更新很有用,这样无论文档怎么更新,插入符都将保持在文档中同一绝对位置。

允许以下更新策略:

默认属性值为 UPDATE_WHEN_ON_EDT

参数:
policy - 它是以下值之一:UPDATE_WHEN_ON_EDTNEVER_UPDATEALWAYS_UPDATE
抛出:
IllegalArgumentException - 如果传入无效的值
从以下版本开始:
1.5
另请参见:
getUpdatePolicy(), adjustVisibility(java.awt.Rectangle), UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE

getUpdatePolicy

public int getUpdatePolicy()
获得文档更新时的插入符移动策略。

返回:
以下值之一:UPDATE_WHEN_ON_EDTNEVER_UPDATEALWAYS_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 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 Threads and Swing


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 可用于获取插入符的当前可见状态,即当前是否绘制的状态。此状态将随插入符的闪烁打开和关闭而更改。

下面的列表显示了调用此方法后 isActiveisVisible 可能的返回值:

setVisible(true):

setVisible(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
返回:
延迟,以毫秒为单位。如果为零,则插入符不闪烁。
另请参见:
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)
将插入符位置和标记设置为某个位置。此方法将选定区域隐式地设置为零。

指定者:
接口 Caret 中的 setDot
参数:
dot - 位置,该位置 >= 0
另请参见:
Caret.setDot(int)

moveDot

public void moveDot(int dot)
将插入符位置移动到某个其他位置。

指定者:
接口 Caret 中的 moveDot
参数:
dot - 位置,该位置 >= 0
另请参见:
Caret.moveDot(int)

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

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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