javax.swing.text

接口
异常
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 包中添加了支持所有 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()
          获取插入符的当前位置。
 Position.Bias getDotBias()
          返回插入符位置的偏差。
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
          返回目前已在此插入符上注册为 FooListener 的所有对象组成的数组。
 Point getMagicCaretPosition()
          获取保存的插入符位置。
 int getMark()
          获取标记的当前位置。
 Position.Bias getMarkBias()
          返回标记的偏差。
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 moveDot(int dot, Position.Bias dotBias)
          将插入符位置移动到指定位置,存在指定偏差。
 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 setDot(int dot, Position.Bias dotBias)
          将插入符位置和标记设置为指定位置,存在指定偏差。
 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,插入符的绝对位置将减小,因为在它之前删除了一个字符。有时候,关闭插入符位置更新很有用,这样无论文档怎么更新,插入符都将保持在文档中同一绝对位置。

允许以下更新策略:

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

默认属性值为 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 方法不是线程安全的,但此方法是线程安全的。有关更多信息,请参阅 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

JDK 1.6 中文手册