Module java.desktop
Package javax.swing.text

Class 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
Caret的默认实现。插入符号呈垂直线状，颜色由关联的JTextComponent的CaretColor属性指定。它可以以BlinkRate属性指定的速率闪烁。

此实现期望两个异步通知源。计时器线程会异步触发，导致插入符号简单地重绘最近的边界框。插入符号还会跟踪文档修改时的变化。通常，这将在事件分发线程上发生，因为某些鼠标或键盘事件的结果。插入符号在同步和异步文档更新上的行为由UpdatePolicy属性控制。新插入符号位置的重绘将在任何情况下在事件线程上发生，因为对modelToView的调用仅在事件线程上是安全的。

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

与关联文本组件绑定的Highlighter默认用于呈现选择。选择外观可以通过提供用于高亮显示的绘制器来自定义。默认情况下，将使用一个绘制器，该绘制器将以关联文本组件中的SelectionColor属性指定的实色进行渲染。这可以通过重新实现getSelectionPainter方法轻松更改。

可以通过重新实现paint方法来实现自定义插入符号外观。如果更改了paint方法，则还应重新实现damage方法，以导致需要重新绘制插入符号的区域。插入符号扩展了Rectangle类，用于保存插入符号上次呈现的边界框。这使得插入符号在移动时可以以线程安全的方式重绘，而无需调用modelToView，因为modelToView在模型更新和视图修复之间是不稳定的（即DocumentListeners的传递顺序不能保证）。

当插入符号位置更改时，魔术插入符号位置设置为null。计时器用于确定新位置（在插入符号更改后）。当计时器触发时，如果魔术插入符号位置仍为null，则将其重置为当前插入符号位置。任何更改插入符号位置并希望魔术插入符号位置保持不变的操作，必须记住魔术插入符号位置，更改光标，然后将魔术插入符号位置设置为其原始值。这有一个好处，即只有希望魔术插入符号位置保持不变的操作（例如打开/向下）需要知道它。

警告: 该类的序列化对象将不兼容未来的Swing版本。当前的序列化支持适用于短期存储或在运行相同Swing版本的应用程序之间的RMI。从1.4开始，已将所有JavaBeans的长期存储支持添加到java.beans包中。请参阅XMLEncoder。

参见:

  • Field Details

    • UPDATE_WHEN_ON_EDT

      public static final int UPDATE_WHEN_ON_EDT
      表示插入符号位置仅在事件分发线程上执行文档更改时才会更新。
      自1.5版本起:
      1.5
      参见:

    • NEVER_UPDATE

      public static final int NEVER_UPDATE
      表示插入符号位置应始终保持在文档中的相同绝对位置，而不考虑任何文档更新，除非由于删除导致文档长度小于当前插入符号位置。在这种情况下，插入符号位置将调整为文档的末尾。
      自1.5版本起:
      1.5
      参见:

    • ALWAYS_UPDATE

      public static final int ALWAYS_UPDATE
      表示插入符号位置始终应根据文档更改进行更新，无论文档更新是在事件分发线程上执行还是不执行。
      自1.5版本起:
      1.5
      参见:

    • listenerList

      protected EventListenerList listenerList
      事件监听器列表。

    • changeEvent

      protected transient ChangeEvent changeEvent
      模型的更改事件。每个模型实例只需要一个ChangeEvent，因为事件的唯一（只读）状态是源属性。此处生成的事件的源始终为“this”。

  • Constructor Details

    • DefaultCaret

      public DefaultCaret()
      构造默认插入符号。

  • Method Details

    • 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

      public int getUpdatePolicy()
      获取文档更新时插入符号的移动策略。
      返回：
      以下值之一：UPDATE_WHEN_ON_EDT、NEVER_UPDATE、ALWAYS_UPDATE
      自：
      1.5
      参见：

    • getComponent

      protected final JTextComponent getComponent()
      获取此插入符号绑定到的文本编辑器组件。
      返回：
      组件

    • repaint

      protected final void repaint()
      使插入符号被绘制。重绘区域是插入符号的边界框（即插入符号矩形或this）。

      此方法是线程安全的，尽管大多数Swing方法不是。有关更多信息，请参阅Swing中的并发性。

    • damage

      protected void damage(Rectangle r)
      损坏插入符号周围的区域，使其在新位置重新绘制。如果重新实现了paint()方法，则还应重新实现此方法。此方法应更新插入符号边界（x、y、宽度和高度）。
      参数：
      r - 插入符号的当前位置
      参见：

    • adjustVisibility

      protected void adjustVisibility(Rectangle nloc)
      滚动关联视图（如果需要）以使插入符号可见。由于应该如何执行此操作在某种程度上是一种策略，因此可以重新实现此方法以更改行为。默认情况下，会在关联组件上调用scrollRectToVisible方法。
      参数：
      nloc - 要滚动到的新位置

    • getSelectionPainter

      protected Highlighter.HighlightPainter getSelectionPainter()
      获取高亮器的绘制器。
      返回：
      绘制器

    • positionCaret

      protected void positionCaret(MouseEvent e)
      尝试根据鼠标事件的坐标从视图到模型（viewToModel()）设置插入符号的位置。
      参数：
      e - 鼠标事件

    • moveCaret

      protected void moveCaret(MouseEvent e)
      尝试根据鼠标事件的坐标从视图到模型（viewToModel()）移动插入符号的位置。如果点和标记不同，这将导致选择。
      参数：
      e - 鼠标事件

    • focusGained

      public void focusGained(FocusEvent e)
      当包含插入符号的组件获得焦点时调用。这是为了在组件可编辑时将插入符号设置为可见。
      指定者：
      focusGained 在接口 FocusListener中实现
      参数：
      e - 焦点事件
      参见：

    • focusLost

      public void focusLost(FocusEvent e)
      当包含插入符号的组件失去焦点时调用。这是为了将插入符号设置为不可见。
      指定者：
      focusLost 在接口 FocusListener中实现
      参数：
      e - 焦点事件
      参见：

    • mouseClicked

      public void mouseClicked(MouseEvent e)
      当鼠标被单击时调用。如果单击是由button1生成的，双击选择一个单词，三次单击选择当前行。
      指定者：
      mouseClicked 在接口 MouseListener中实现
      参数：
      e - 鼠标事件
      参见：

    • mousePressed

      public void mousePressed(MouseEvent e)
      如果按下按钮1，则实现此方法以请求关联文本组件的焦点，并设置插入符号位置。如果按住Shift键，则插入符号将被移动，可能导致选择，否则插入符号位置将设置为新位置。如果组件未启用，则不会请求焦点。
      指定者：
      mousePressed 在接口 MouseListener中实现
      参数：
      e - 鼠标事件
      参见：

    • mouseReleased

      public void mouseReleased(MouseEvent e)
      当鼠标释放时调用。
      指定者：
      mouseReleased 在接口 MouseListener中实现
      参数：
      e - 鼠标事件
      参见：

    • mouseEntered

      public void mouseEntered(MouseEvent e)
      当鼠标进入区域时调用。
      指定者：
      mouseEntered 在接口 MouseListener中实现
      参数：
      e - 鼠标事件
      参见：

    • mouseExited

      public void mouseExited(MouseEvent e)
      当鼠标退出区域时调用。
      指定者：
      mouseExited 在接口 MouseListener中实现
      参数：
      e - 鼠标事件
      参见：

    • mouseDragged

      public void mouseDragged(MouseEvent e)
      根据鼠标指针当前位置移动插入符号位置。这实际上扩展了选择。默认情况下，仅对鼠标按钮1执行此操作。
      指定者:
      mouseDragged 在接口 MouseMotionListener中
      参数:
      e - 鼠标事件
      参见:

    • mouseMoved

      public void mouseMoved(MouseEvent e)
      当鼠标移动时调用。
      指定者:
      mouseMoved 在接口 MouseMotionListener中
      参数:
      e - 鼠标事件
      参见:

    • paint

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

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

      指定者:
      paint 在接口 Caret中
      参数:
      g - 图形上下文
      参见:

    • install

      public void install(JTextComponent c)
      当UI安装到JTextComponent的接口中时调用。这可用于访问由此接口的实现导航的模型。将dot和mark设置为0，并建立文档、属性更改、焦点、鼠标和鼠标移动侦听器。
      指定者:
      install 在接口 Caret中
      参数:
      c - 组件
      参见:

    • deinstall

      public void deinstall(JTextComponent c)
      当UI从JTextComponent的接口中移除时调用。用于注销附加的任何侦听器。
      指定者:
      deinstall 在接口 Caret中
      参数:
      c - 组件
      参见:

    • addChangeListener

      public void addChangeListener(ChangeListener l)
      添加侦听器以跟踪插入符位置的更改。
      指定者:
      addChangeListener 在接口 Caret中
      参数:
      l - 侦听器
      参见:

    • removeChangeListener

      public void removeChangeListener(ChangeListener l)
      移除跟踪插入符位置更改的侦听器。
      指定者:
      removeChangeListener 在接口 Caret中
      参数:
      l - 侦听器
      参见:

    • getChangeListeners

      public ChangeListener[] getChangeListeners()
      返回在此插入符上注册的所有更改侦听器的数组。
      返回:
      所有此插入符的ChangeListener或如果当前未注册任何更改侦听器，则返回空数组
      自:
      1.4
      参见:

    • fireStateChanged

      protected void fireStateChanged()
      通知所有已注册对此事件类型感兴趣的侦听器。事件实例是使用传递给fire方法的参数延迟创建的。侦听器列表按照从后到前的顺序处理。
      参见:

    • getListeners

      public <T extends EventListener> T[] getListeners(Class<T> listenerType)
      返回当前在此插入符上注册为FooListener的所有对象的数组。FooListener是使用addFooListener方法注册的。

      您可以使用类字面量（例如FooListener.class）指定listenerType参数。例如，您可以使用以下代码查询DefaultCaret c的更改侦听器：

      ChangeListener[] cls = (ChangeListener[])(c.getListeners(ChangeListener.class));
      如果不存在此类侦听器，则此方法返回一个空数组。
      类型参数:
      T - 侦听器类型
      参数:
      listenerType - 请求的侦听器类型
      返回:
      在此组件上注册为FooListener的所有对象的数组，如果尚未添加此类侦听器，则返回一个空数组
      抛出:
      ClassCastException - 如果listenerType未指定实现java.util.EventListener的类或接口
      自:
      1.3
      参见:

    • setSelectionVisible

      public void setSelectionVisible(boolean vis)
      更改选择可见性。
      指定者:
      setSelectionVisible 在接口 Caret中
      参数:
      vis - 新的可见性

    • isSelectionVisible

      public boolean isSelectionVisible()
      检查当前选择是否可见。
      指定者:
      isSelectionVisible 在接口 Caret中
      返回:
      如果选择可见，则为true

    • isActive

      public boolean isActive()
      确定插入符当前是否活动。

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

      返回:
      如果活动则为true，否则为false
      自:
      1.5
      参见:

    • isVisible

      public boolean isVisible()
      指示插入符当前是否可见。随着插入符的闪烁，此方法的返回值将在插入符绘制时为true，在插入符不绘制时为false。 isActive指示插入符当前是否处于闪烁状态，即它可以可见，而isVisible指示插入符实际上是否可见。

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

      指定者:
      isVisible 在接口 Caret中
      返回:
      如果可见则为true，否则为false
      参见:

    • 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
      指定者:
      setVisible 在接口 Caret中
      参数:
      e - 可见性规定者
      参见:

    • setBlinkRate

      public void setBlinkRate(int rate)
      设置插入符号的闪烁速率。
      指定者:
      setBlinkRate 在接口 Caret中
      参数:
      rate - 以毫秒为单位的速率，0表示停止闪烁
      参见:

    • getBlinkRate

      public int getBlinkRate()
      获取插入符号的闪烁速率。
      指定者:
      getBlinkRate 在接口 Caret中
      返回:
      以毫秒为单位的延迟。如果为零，则插入符号不会闪烁。
      参见:

    • getDot

      public int getDot()
      获取插入符号的当前位置。
      指定者:
      getDot 在接口 Caret中
      返回:
      位置 >= 0
      参见:

    • getMark

      public int getMark()
      获取标记的当前位置。如果存在选择，则插入符号和标记将不相同。
      指定者:
      getMark 在接口 Caret中
      返回:
      位置 >= 0
      参见:

    • setDot

      public void setDot(int dot)
      将插入符号位置和标记设置为指定位置，并具有正向偏差。这隐式地将选择范围设置为零。
      指定者:
      setDot 在接口 Caret中
      参数:
      dot - 位置 >= 0
      参见:

    • moveDot

      public void moveDot(int dot)
      将插入符号位置移动到指定位置，并具有正向偏差。
      指定者:
      moveDot 在接口 Caret中
      参数:
      dot - 位置 >= 0
      参见:

    • moveDot

      public void moveDot(int dot, Position.Bias dotBias)
      将插入符号位置移动到指定位置，并具有指定的偏差。
      参数:
      dot - 位置 >= 0
      dotBias - 此位置的偏差，非null
      抛出:
      IllegalArgumentException - 如果偏差为null
      自:
      1.6
      参见:

    • setDot

      public void setDot(int dot, Position.Bias dotBias)
      将插入符号位置和标记设置为指定位置，并具有指定的偏差。这隐式地将选择范围设置为零。
      参数:
      dot - 位置 >= 0
      dotBias - 此位置的偏差，非null
      抛出:
      IllegalArgumentException - 如果偏差为null
      自:
      1.6
      参见:

    • getDotBias

      public Position.Bias getDotBias()
      返回插入符号位置的偏差。
      返回:
      插入符号位置的偏差
      自:
      1.6

    • getMarkBias

      public Position.Bias getMarkBias()
      返回标记的偏差。
      返回:
      标记的偏差
      自:
      1.6

    • setMagicCaretPosition

      public void setMagicCaretPosition(Point p)
      保存当前插入符号位置。在发生插入符号上/下操作时使用，移动到具有不同结束位置的行之间。
      指定者:
      setMagicCaretPosition 在接口 Caret中
      参数:
      p - 位置
      参见:

    • getMagicCaretPosition

      public Point getMagicCaretPosition()
      获取保存的插入符号位置。
      指定者:
      getMagicCaretPosition 在接口 Caret中
      返回:
      位置见 #setMagicCaretPosition
      参见:

    • equals

      public boolean equals(Object obj)
      将此对象与指定对象进行比较。不希望比较矩形的超类行为，因此更改为Object行为。
      覆盖:
      equals 在类 Rectangle中
      参数:
      obj - 要与此字体进行比较的对象
      返回:
      如果对象相等，则为true; 否则为false
      参见: