javax.swing.text
类 JTextComponent

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.text.JTextComponent

所有已实现的接口：

ImageObserver, MenuContainer, Serializable, Accessible, Scrollable

直接已知子类：

JEditorPane, JTextArea, JTextField

public abstract class JTextComponent
extends JComponent
implements Scrollable, Accessible

JTextComponent 是 swing 文本组件的基类。它会试着与 java.awt.TextComponent 类兼容，并且在此理应如此。还提供其他额外灵活性（不包括可插入 UI 和 bean 支持）服务。有关如何使用此类提供的功能的信息，请参阅 The Java Tutorial 中的 General Rules for Using Text Components 一节。

插入符更改

插入符是 swing 文本组件中的可插入对象。将插入符位置和选择的更改通知发送到已向文本组件注册的 CaretListener 接口的实现。如果尚未设置定制插入符，则该 UI 将安装默认插入符。
默认情况下，该插入符会跟踪在事件指派线程上执行的所有更改，并且如果插入发生在插入符位置或之前，或者移除发生在插入符位置之前，则相应地更新其位置。DefaultCaret 尝试使自己可见，这将导致 JScrollPane 内的文本组件发生滚动。DefaultCaret.setUpdatePolicy(int) 方法可以更改默认的插入符行为。
注：不可编辑的文本组件也有插入符，尽管可能不绘制它。

命令

文本组件提供许多可能用于操作组件的命令。这实质上是组件表示其功能的方式。这些都将根据 swing Action 接口使用 TextAction 实现来表示。文本组件支持的命令集合可以使用 getActions() 方法查找。这些操作可以绑定到由按键等触发的键事件上。

文本输入

文本组件支持灵活而且国际化的文本输入，在使用 keymap 和输入法框架的同时维护与 AWT 侦听器模型的兼容性。

Keymap 让应用程序将击键绑定到操作上。为了允许 keymap 在整个多文本组件上共享，它们可以使用扩展 TextAction 的操作。TextAction 可以确定哪个 JTextComponent 最近有或以前有过焦点，并因此成为该操作的执行者（在此情况下，发送到该操作的 ActionEvent 不包含作为其源的目标文本组件）。

input method framework 让文本组件与输入法交互，分隔预处理事件的软件组件，来让用户使用非常有限的几个键盘键输入成千上万个不同的字符。JTextComponent 是该框架的一个活动客户端，因此它可实现与输入法交互的首选用户界面。因此，有些键事件因为受输入法处理而无法到达文本组件，而有些文本输入不是作为键事件而是作为在 InputMethodEvent 内的提交文本到达文本组件的。完整的文本输入是 keyTyped 键事件中的字符和输入法事件中的提交文本的结合。

AWT 侦听器模型让应用程序将事件侦听器附加到组件，以便将事件绑定到操作。Swing 鼓励使用 keymap 替代侦听器，但要通过使用它为侦听器提供获得事件的机会来维护与侦听器的兼容性。

键盘事件和输入法事件通过以下几个阶段进行处理，每个阶段都能使用该事件：

Stage	KeyEvent	InputMethodEvent
1.	输入法	（在此处生成）
2.	焦点管理器
3.	注册的键侦听器	注册的输入法侦听器
4.		在 JTextComponent 中的输入法处理
5.	使用当前 keymap 进行 keymap 处理
6.	在 JComponent 中进行键盘处理（如加速键、组件导航等）

要维护与侦听键事件但不知道输入法事件的应用程序的兼容性，在阶段 4 中的输入法处理会提供不处理输入法事件的组件的兼容性模式。对于这些组件，可将提交文本转换为 keyTyped 键事件，并在阶段 3 开始的键事件管线中进行处理，而不是在输入法事件管线中处理。

默认情况下，组件将创建一个作为默认 keymap 由所有 JTextComponent 实例共享的 keymap（名为 DEFAULT_KEYMAP）。通常，外观实现将安装一个不同的 keymap，以便把另一个 keymap 中找不到的绑定解析为默认 keymap。该绑定最少包括：

• 将内容插入打印键编辑器。
• 使用 backspace 和 del 键移除内容。
• 前后移动的插入符

模型/视图拆分

文本组件具有模型/视图拆分功能。文本组件会将用于表示模型、视图和控制器的对象拉在一起。文本文档模型可以由充当该模型观察者的其他视图共享（如，多个组件可以共享一个文档）。

该模型由 Document 接口定义。此模型应提供灵活的文本存储机制，以在编辑过程中跟踪更改，并且可以扩展为更复杂的模型。该模型接口旨在捕获 SGML（用于表示多种内容的系统）提供的表达式功能。每次修改文档都会以 DocumentEvent 形式将更改的详细信息通知给所有观察者，允许视图与模型保持最新。将此事件发送给实现了 DocumentListener 接口且注册为需要正在接受观察的模型的观察者。

位置信息

提供确定视图中文本位置的功能。确定此信息有两个方法，modelToView(int) 和 viewToModel(java.awt.Point)。

撤消/恢复支持

提供对编辑历史机制的支持，以允许进行撤消/恢复操作。默认情况下文本组件本身不提供历史缓冲区，但确实提供可以与历史缓冲区一起使用的 UndoableEdit 记录以提供撤消/恢复支持。该支持由 Document 模型提供，该模型允许用户附加 UndoableEditListener 实现。

线程安全

swing 文本组件对线程安全操作提供一定程度的支持。因为文本组件的可配置性级别高，所以可以回避所提供的保护。该保护主要来自模型，因此 AbstractDocument 的文档会描述提供的假定保护。异步调用的安全方法标记为注释。

换行

有关如果处理换行的讨论，请参阅 DefaultEditorKit。

打印支持

提供了几个 print 方法进行基本文档打印。如果需要更高级的打印，请使用 getPrintable(java.text.MessageFormat, java.text.MessageFormat) 方法。

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

另请参见：

Document, DocumentEvent, DocumentListener, Caret, CaretEvent, CaretListener, TextUI, View, ViewFactory

FOCUS_ACCELERATOR_KEY

public static final String FOCUS_ACCELERATOR_KEY

焦点加速键的绑定 (bound) 属性名称。

另请参见：

常量字段值

DEFAULT_KEYMAP

public static final String DEFAULT_KEYMAP

将由所有 JTextComponent 实例共享的默认 keymap，除非这些实例已有另一个 keymap 集合。

另请参见：

常量字段值

JTextComponent

public JTextComponent()

创建一个新的 JTextComponent。建立插入符事件的侦听器，并安装可插入的 UI。将组件标记为可编辑状态。不使用任何布局管理器，因为布局受文本的视图子系统管理。文档模型被设置为 null。

getUI

public TextUI getUI()

获取此面向文本的编辑器的用户界面工厂。

返回：

工厂

setUI

public void setUI(TextUI ui)

设置此面向文本的编辑器的用户界面工厂。

参数：

ui - 工厂

updateUI

public void updateUI()

重新加载可插入的 UI。用于获取新界面的键是 getUIClassID()。该 UI 的类型是 TextUI。设置该 UI 之后调用 invalidate。

覆盖：

类 JComponent 中的 updateUI

另请参见：

JComponent.setUI(javax.swing.plaf.ComponentUI), UIManager.getLookAndFeel(), UIManager.getUI(javax.swing.JComponent)

addCaretListener

public void addCaretListener(CaretListener listener)

添加插入符侦听器，以便侦听任何插入符的更改通知。

参数：

listener - 要添加的侦听器

另请参见：

CaretEvent

removeCaretListener

public void removeCaretListener(CaretListener listener)

移除插入符侦听器。

参数：

listener - 要移除的侦听器

另请参见：

CaretEvent

getCaretListeners

public CaretListener[] getCaretListeners()

返回在此文本组件上已注册的所有插入符侦听器的数组。

返回：

组件的所有 CaretListener；如果当前没有注册任何插入符侦听器，则返回一个空数组

从以下版本开始：

1.4

另请参见：

addCaretListener(javax.swing.event.CaretListener), removeCaretListener(javax.swing.event.CaretListener)

fireCaretUpdate

protected void fireCaretUpdate(CaretEvent e)

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

参数：

e - 事件

另请参见：

EventListenerList

setDocument

public void setDocument(Document doc)

将编辑器与文本文档关联。使用当前已注册的工厂构建一个文档视图，重新确认后由编辑器显示该文档。PropertyChange 事件 ("document") 被传播到每个侦听器。

参数：

doc - 要显示/编辑的文档

另请参见：

getDocument()

getDocument

public Document getDocument()

获取与编辑器关联的模型。此方法主要是让 UI 以最少的要求成为文本编辑器的声明次数获取。子类将返回通常将用于扩展 Document 的实际模型类型。

返回：

模型

setComponentOrientation

public void setComponentOrientation(ComponentOrientation o)

从类 Component 复制的描述

设置语言敏感的方向，用于排序此组件内的元素或文本。语言敏感的 LayoutManager 和 Component 子类使用此属性来确定如何布局并绘制组件。

在构造时，组件的方向设置为 ComponentOrientation.UNKNOWN，表示尚未显式地指定它。UNKNOWN 方向的行为与 ComponentOrientation.LEFT_TO_RIGHT 相同。

要设置单个组件的方向，请使用此方法。要设置整个组件层次结构的方向，请使用 applyComponentOrientation。

覆盖：

类 Component 中的 setComponentOrientation

另请参见：

ComponentOrientation

getActions

public Action[] getActions()

获取编辑器的命令列表。这是嵌入的 UI 所支持的命令列表，该 UI 通过编辑器本身支持的命令集进行扩充。这些命令对于绑定到事件是很有用的，例如在 keymap 中。

返回：

命令列表

setMargin

public void setMargin(Insets m)

设置组件的边框和它的文本之间的空白。文本组件的默认 Border 对象将使用此值创建适当的空白。不过，如果在文本组件上设置非默认边框，则由 Border 对象负责创建适当的空白（其他情况下实际上忽略此属性）。这会导致重绘该组件。PropertyChange 事件 ("margin") 被发送到所有侦听器。

参数：

m - 边框和文本之间的空间

getMargin

public Insets getMargin()

返回文本组件的边框和它的文本之间的空白。

返回：

空白

setNavigationFilter

public void setNavigationFilter(NavigationFilter filter)

设置 NavigationFilter。NavigationFilter 作为一种限制光标移动的方式由 DefaultCaret 和默认光标移动操作使用。

从以下版本开始：

1.4

getNavigationFilter

public NavigationFilter getNavigationFilter()

返回 NavigationFilter。NavigationFilter 作为一种限制光标移动的方式由 DefaultCaret 和默认光标移动操作使用。null 返回值意味着光标移动和选择不受限制。

返回：

NavigationFilter

从以下版本开始：

1.4

getCaret

public Caret getCaret()

获取允许在视图上进行面向文本导航的插入符。

返回：

插入符

setCaret

public void setCaret(Caret c)

设置要使用的插入符。默认情况下，这将由安装的 UI 设置。如果需要，还可以更改为定制插入符。设置插入符会导致触发一个 PropertyChange 事件 ("caret")。

参数：

c - 插入符

另请参见：

getCaret()

getHighlighter

public Highlighter getHighlighter()

获取负责进行高亮显示的对象。

返回：

highlighter

setHighlighter

public void setHighlighter(Highlighter h)

设置要使用的 highlighter。默认情况下，这将由安装的 UI 设置。如果需要，还可以更改为自定义 highlighter。可以将 highlighter 设置为 null，以禁用它。安装新 highlighter 时，将触发一个 PropertyChange 事件 ("highlighter")。

参数：

h - highlighter

另请参见：

getHighlighter()

setKeymap

public void setKeymap(Keymap map)

设置用于将事件绑定到操作的 keymap。设置为 null 可有效地禁用键盘输入。安装新 keymap 时将触发一个 PropertyChange 事件 ("keymap")。

参数：

map - keymap

另请参见：

getKeymap()

setDragEnabled

public void setDragEnabled(boolean b)

开启或关闭自动拖动处理。要启用自动拖动处理，应该将此属性设置为 true，并且组件的 TransferHandler 必须为非 null。dragEnabled 属性的默认值为 false。

遵守此属性并识别用户拖动动作的作业取决于外观实现，特别是组件的 TextUI。启用自动拖动处理时，只要用户在选择上按下鼠标按钮并将鼠标移动几个像素，多数外观（包括那些子类化 BasicLookAndFeel 的外观）就会开始拖放操作。因此将此属性设置为 true 可以对选择行为产生微妙的影响。

如果在忽略此属性的情况下使用外观，仍然可以通过在组件的 TransferHandler 上调用 exportAsDrag 开始拖放操作。

参数：

b - 是否启用自动拖动处理

抛出：

HeadlessException - 如果 b 为 true，并且 GraphicsEnvironment.isHeadless() 返回 true

从以下版本开始：

1.4

另请参见：

GraphicsEnvironment.isHeadless(), getDragEnabled(), JComponent.setTransferHandler(javax.swing.TransferHandler), TransferHandler

getDragEnabled

public boolean getDragEnabled()

返回是否启用自动拖动处理。

返回：

dragEnabled 属性的值

从以下版本开始：

1.4

另请参见：

setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)

设置此组件的放置模式，为了向后兼容性，此属性的默认值为 DropMode.USE_SELECTION。但是，为了便于用户使用，建议使用 DropMode.INSERT。它还提供类似于在文本位置之间的放置操作行为，但这样做时不影响实际文本选择和插入符位置。

JTextComponents 支持以下放置模式：

• DropMode.USE_SELECTION
• DropMode.INSERT

放置模式只在此组件具有接受放置的 TransferHandler 时才有意义。

参数：

dropMode - 要使用的放置模式

抛出：

IllegalArgumentException - 如果不支持该放置模式或放置模式为 null

从以下版本开始：

1.6

另请参见：

getDropMode(), getDropLocation(), JComponent.setTransferHandler(javax.swing.TransferHandler), TransferHandler

getDropMode

public final DropMode getDropMode()

返回此组件的放置模式。

返回：

此组件的放置模式

从以下版本开始：

1.6

另请参见：

setDropMode(javax.swing.DropMode)

getDropLocation

public final JTextComponent.DropLocation getDropLocation()

返回在组件上进行 DnD 操作过程中此组件在视觉上指示为放置位置的位置；如果当前没有显示任何位置，则返回 null。

此方法不用于从 TransferHandler 查询放置位置，因为只有在返回 TransferHandler 的 canImport 并允许显示位置后才设置放置位置。

此属性更改时，组件将触发名为 "dropLocation" 的属性更改事件。

返回：

放置位置

从以下版本开始：

1.6

另请参见：

setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

getKeymap

public Keymap getKeymap()

获取当前在此文本组件中活动的 keymap。

返回：

keymap

addKeymap

public static Keymap addKeymap(String nm,
                               Keymap parent)

将一个新 keymap 添加到 keymap 层次结构。Keymap 绑定自下向上进行解析，所以在子级中指定的属性将重写父级中指定的属性。

参数：

nm - keymap 的名称（必须为文档中命名的 keymap 集合中唯一的一个）；如果 keymap 是未命名的，则该名称可以为 null，但调用者负责管理返回的引用，因为未命名的 keymap 无法按名称获取

parent - 父级 keymap；如果未指定的绑定不需要在其他某个 keymap 中解析，则此 keymap 可以为 null

返回：

keymap

removeKeymap

public static Keymap removeKeymap(String nm)

移除以前添加到文档中的已命名 keymap。具有 null 名称的 Keymap 可以不以此方式移除。

参数：

nm - 要移除的 keymap 的名称

返回：

已移除的 keymap

getKeymap

public static Keymap getKeymap(String nm)

获取以前添加到文档中的已命名 keymap。此 keymap 不与以 null 命名的 keymap 一起使用。

参数：

nm - keymap 的名称

返回：

keymap

loadKeymap

public static void loadKeymap(Keymap map,
                              JTextComponent.KeyBinding[] bindings,
                              Action[] actions)

加载带有一组绑定的 keymap。这可用于取得一个静态定义表，并将它们加载到某个 keymap 中。以下示例说明了将一些键绑定到与 JTextComponent 关联的剪切、复制和粘贴操作。完成此操作的代码片段可能与以下形式一样：

   static final JTextComponent.KeyBinding[] defaultBindings = {
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_C, InputEvent.CTRL_MASK),
       DefaultEditorKit.copyAction),
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_V, InputEvent.CTRL_MASK),
       DefaultEditorKit.pasteAction),
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_X, InputEvent.CTRL_MASK),
       DefaultEditorKit.cutAction),
   };

   JTextComponent c = new JTextPane();
   Keymap k = c.getKeymap();
   JTextComponent.loadKeymap(k, defaultBindings, c.getActions());
 
 

绑定和操作的集合可以为空，但必须为非 null。

参数：

map - keymap

bindings - 绑定

actions - 操作集合

getCaretColor

public Color getCaretColor()

获取用于呈现插入符的当前颜色。

返回：

颜色

setCaretColor

public void setCaretColor(Color c)

设置用于呈现插入符的当前颜色。设置为 null 可有效地还原默认颜色。设置颜色会导致触发一个 PropertyChange 事件 ("caretColor")。

参数：

c - 颜色

另请参见：

getCaretColor()

getSelectionColor

public Color getSelectionColor()

获取用于呈现选定的当前颜色。

返回：

颜色

setSelectionColor

public void setSelectionColor(Color c)

设置用于呈现选定的当前颜色。将颜色设置为 null 的方法与设置 Color.white 的方法相同。设置颜色会导致一个 PropertyChange 事件 ("selectionColor")。

参数：

c - 颜色

另请参见：

getSelectionColor()

getSelectedTextColor

public Color getSelectedTextColor()

获取用于呈现选定文本的当前颜色。

返回：

颜色

setSelectedTextColor

public void setSelectedTextColor(Color c)

设置用于呈现选定文本的当前颜色。将颜色设置为 null 的方法与设置 Color.black 的方法相同。设置颜色会导致触发一个 PropertyChange 事件 ("selectedTextColor")。

参数：

c - 颜色

另请参见：

getSelectedTextColor()

getDisabledTextColor

public Color getDisabledTextColor()

获取用于呈现禁用文本的当前颜色。

返回：

颜色

setDisabledTextColor

public void setDisabledTextColor(Color c)

设置用于呈现禁用文本的当前颜色。设置颜色会触发一个 PropertyChange 事件 ("disabledTextColor")。

参数：

c - 颜色

另请参见：

getDisabledTextColor()

replaceSelection

public void replaceSelection(String content)

用给定字符串所表示的新内容替换当前选定的内容。如果没有选择的内容，则该操作插入给定的文本。如果没有替换文本，则该操作移除当前选择的内容。

这是插入内容操作的默认实现使用的一种方法，该操作绑定了 keymap 操作。

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

参数：

content - 要替换选定内容的内容

getText

public String getText(int offs,
                      int len)
               throws BadLocationException

获取由组件表示的文本部分。如果长度为 0，则返回空字符串。

参数：

offs - 偏移量，该值 >= 0

len - 长度，该值 >= 0

返回：

文本

抛出：

BadLocationException - 如果偏移量或长度无效

modelToView

public Rectangle modelToView(int pos)
                      throws BadLocationException

将模型中给定位置转换为视图坐标系统中的位置。组件大小必须为一个正值才能用于计算此转换（即在确定组件大小之前不能计算布局）。该组件未必是可见或已绘制的。

参数：

pos - 位置，该值 >= 0

返回：

直角坐标，其在坐标系中的位置为 (r.x, r.y)；如果组件尚不具有正值大小，则返回 null。

抛出：

BadLocationException - 如果给定位置不表示关联文档中的有效位置

另请参见：

TextUI.modelToView(javax.swing.text.JTextComponent, int)

viewToModel

public int viewToModel(Point pt)

将视图坐标系统中的给定位置转换为模型中最具代表性的位置。组件大小必须为一个正值才能用于计算此转换（即在确定组件大小之前不能计算布局）。该组件不必是可见或已绘制的。

参数：

pt - 视图中要转换的位置

返回：

文档起始部分的偏移量，该值 >= 0；如果组件尚不具有正值大小，则返回 -1。

另请参见：

TextUI.viewToModel(javax.swing.text.JTextComponent, java.awt.Point)

cut

public void cut()

将关联文本模型中当前选定的范围传输到系统剪贴板，并从模型中移除内容。重新设置当前选定。对于 null 选定不执行任何操作。

另请参见：

Toolkit.getSystemClipboard(), Clipboard

copy

public void copy()

将关联文本模型中当前选定的范围传输到系统剪贴板，并在文本模型中保留内容。当前选定保持原样。对于 null 选定不执行任何操作。

另请参见：

Toolkit.getSystemClipboard(), Clipboard

paste

public void paste()

将系统剪贴板的内容传输到关联的文本模型中。如果在关联视图中有选定的内容，则使用剪贴板的内容替换它。如果没有选定的内容，则将剪贴板插入关联视图中当前插入位置的前面。如果剪贴板为空，则不执行任何操作。

另请参见：

replaceSelection(java.lang.String), Toolkit.getSystemClipboard(), Clipboard

moveCaretPosition

public void moveCaretPosition(int pos)

将插入符移动到新的位置，同时保留最后一次调用 setCaretPosition 之前定义的标记。这就构成了一个选定。如果文档为 null，则不执行任何操作。位置必须在 0 和组件的文本长度之间，否则将抛出异常。

参数：

pos - 位置

抛出：

IllegalArgumentException - 如果 position 提供的值小于 0 或大于组件的文本长度

另请参见：

setCaretPosition(int)

setFocusAccelerator

public void setFocusAccelerator(char aKey)

设置将导致接收的文本组件获取焦点的加速键。加速键将是 alt 键和给定字符（已转换为大写）的修改键。默认情况下，不存在焦点加速键。以前的任何加速键设置都将被取代。'\0' 键设置将被注册，并具有关闭焦点加速键的效果。设置新键时，将触发一个 PropertyChange 事件 (FOCUS_ACCELERATOR_KEY)。

参数：

aKey - 键

另请参见：

getFocusAccelerator()

getFocusAccelerator

public char getFocusAccelerator()

返回将导致接收文本组件获取焦点的加速键。如果没有设置焦点加速键，则返回 '\0'。

返回：

键

read

public void read(Reader in,
                 Object desc)
          throws IOException

根据流进行初始化。此方法创建一个适合于组件类型的模型，并根据流初始化该模型。默认情况下，此方法将以纯文本的方式加载该模型。该模型以前的内容将被丢弃。

参数：

in - 从中读取的流

desc - 描述流的对象；此对象可以是一个字符串、一个 File、一个 URL 等。有些种类的文档（如 html）或许能够使用此信息；如果为非 null，则将其作为文档的属性添加

抛出：

IOException - 如果使用该流初始化

另请参见：

EditorKit.createDefaultDocument(), setDocument(javax.swing.text.Document), PlainDocument

write

public void write(Writer out)
           throws IOException

将模型的内容存储到给定的流中。默认情况下，此方法将以纯文本的方式存储该模型。

参数：

out - 输出流

抛出：

IOException - 如果发生任何 I/O 错误

removeNotify

public void removeNotify()

从类 JComponent 复制的描述

通知此组件它不再有父组件。调用此方法时，移除父组件链中所有已设置的 KeyboardAction。

覆盖：

类 JComponent 中的 removeNotify

另请参见：

JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

setCaretPosition

public void setCaretPosition(int position)

设置 TextComponent 的文本插入符的位置。注意，插入符可跟踪更改，所以如果组件的底层文本被更改，则此位置可能会移动。如果文档为 null，则不执行任何操作。位置必须在 0 和组件的文本长度之间，否则将抛出异常。

参数：

position - 位置

抛出：

IllegalArgumentException - 如果 position 提供的值小于 0 或大于组件的文本长度

getCaretPosition

public int getCaretPosition()

返回文本组件的文本插入符的位置。

返回：

文本组件的文本插入符的位置，该值 >= 0

setText

public void setText(String t)

将此 TextComponent 文本设置为指定文本。如果该文本为 null 或空，则具有只删除旧文本的效果。插入文本时，得到的插入符的位置由该插入符类的实现确定。

虽然大多数 Swing 方法不是线程安全的，但此方法是线程安全的。有关更多信息，请参阅 How to Use Threads。 注意，文本不是绑定属性，所以更改时不触发 PropertyChangeEvent。要侦听文本的更改，请使用 DocumentListener。

参数：

t - 要设置的新文本

另请参见：

getText(int, int), DefaultCaret

getText

public String getText()

返回此 TextComponent 中包含的文本。如果底层文档为 null，则将给出 NullPointerException。注意，文本不是绑定属性，所以更改时不触发 PropertyChangeEvent。要侦听文本的更改，请使用 DocumentListener。

返回：

文本

抛出：

NullPointerException - 如果文档为 null

另请参见：

setText(java.lang.String)

getSelectedText

public String getSelectedText()

返回此 TextComponent 中包含的选定文本。如果选定为 null 或文档为空，则返回 null。

返回：

文本

抛出：

IllegalArgumentException - 如果由于某种原因选定没有到文档的有效映射

另请参见：

setText(java.lang.String)

isEditable

public boolean isEditable()

返回指示此 TextComponent 是否可编辑的 boolean。

返回：

boolean 值

另请参见：

setEditable(boolean)

setEditable

public void setEditable(boolean b)

设置指定的 boolean 变量，以指示此 TextComponent 是否应该为可编辑的。当状态更改时，将触发 PropertyChange 事件（"editable"）。

参数：

b - 要设置的 boolean

另请参见：

isEditable()

getSelectionStart

public int getSelectionStart()

返回选定文本的起始位置。如果是空文档，则返回 0；如果没有选定，则返回点值。

返回：

起始位置，该值 >= 0

setSelectionStart

public void setSelectionStart(int selectionStart)

将选定起始点设置为指定的位置。新的起始点将限制在当前选定的结束点或之前。

这可用于在 java.awt.TextComponent 上调用此方法的代码向后兼容。实现此方法以转发给 Caret 实现，后者是维护实际选定的位置。

参数：

selectionStart - 文本的起始位置，该值 >= 0

getSelectionEnd

public int getSelectionEnd()

返回选定文本的结束位置。如果文本为空，则返回 0；如果没有选择，则返回点值。

返回：

结束位置，该值 >= 0

setSelectionEnd

public void setSelectionEnd(int selectionEnd)

将选择结束点设置为指定的位置。新的结束点限制在当前选定开始位置处或之后。

这可用于在 java.awt.TextComponent 上调用此方法的代码向后兼容。实现此方法以转发 Caret 实现，后者是维护实际选定的位置。

参数：

selectionEnd - 文本的结束位置，该值 >= 0

select

public void select(int selectionStart,
                   int selectionEnd)

选定指定的开始和结束位置之间的文本。

此方法设置选定文本的开始位置和结束位置，并强行限制开始位置必须大于等于零。结束位置必须大于等于开始位置，并大于等于文本组件的文本长度。

如果调用者提供不一致或超出限度的值，则该方法静默地实施这些限制，并且不会失败。要特别指出的是，如果开始位置或结束位置大于文本长度，则将它重置为等于文本长度。如果开始位置小于零，则将它重置为零，如果结束位置小于开始位置，则将它重置为开始位置。

此调用是为向后兼容性提供的。将其作为调用 setCaretPosition 的途径，接着再调用 moveCaretPosition。管理选定的首选方法是直接调用这些方法。

参数：

selectionStart - 文本的起始位置

selectionEnd - 文本的结束位置

另请参见：

setCaretPosition(int), moveCaretPosition(int)

selectAll

public void selectAll()

选择 TextComponent 中的所有文本。在 null 或空文档上不执行任何操作。

getToolTipText

public String getToolTipText(MouseEvent event)

返回用作 event 的工具提示的字符串。这将返回以下内容之一：

1. 如果 setToolTipText 已使用非 null 值调用，则它将被返回；否则
2. 在 UI 上调用 getToolTipText 的值将被返回。

默认情况下，JTextComponent 不使用 ToolTipManager 注册它本身。这意味着只有已在 ToolTipManager 上调用了 registerComponent 工具提示才在 TextUI 上显示。

覆盖：

类 JComponent 中的 getToolTipText

参数：

event - 关联事件

返回：

用作 event 的工具提示的字符串

另请参见：

JComponent.setToolTipText(java.lang.String), TextUI.getToolTipText(javax.swing.text.JTextComponent, java.awt.Point), ToolTipManager.registerComponent(javax.swing.JComponent)

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()

返回视图组件视口的首选大小。实现此方法以执行返回组件的首选大小的默认行为。

指定者：

接口 Scrollable 中的 getPreferredScrollableViewportSize

返回：

其视图为此 Scrollable 的 JViewport 的 preferredSize

另请参见：

JComponent.getPreferredSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)

显示逻辑行或列的组件应计算滚动增量，它将根据方向的值完全公开一个新的行或列。理想情况下，组件应通过返回需要的距离来处理一个部分公开的行或列，以便完全公开此项。

此操作的默认实现是只返回可视区域的 10%。子类或许能够提供一个更加合理的值。

指定者：

接口 Scrollable 中的 getScrollableUnitIncrement

参数：

visibleRect - 视口中可见的视图区域

orientation - SwingConstants.VERTICAL 或 SwingConstants.HORIZONTAL

direction - 小于零向上/左滚动，大于零向下/右滚动

返回：

在指定方向滚动的“单位”增量

抛出：

IllegalArgumentException - 如果方向无效

另请参见：

JScrollBar.setUnitIncrement(int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)

显示逻辑行或列的组件应计算滚动增量，它将根据方向的值完全公开一个行块或列块。

此操作的默认实现是只返回可视区域。子类将或许能够提供一个更加合理的值。

指定者：

接口 Scrollable 中的 getScrollableBlockIncrement

参数：

visibleRect - 视口中可见的视图区域

orientation - SwingConstants.VERTICAL 或 SwingConstants.HORIZONTAL

direction - 小于零向上/左滚动，大于零向下/右滚动

返回：

在指定方向滚动的“块”增量

另请参见：

JScrollBar.setBlockIncrement(int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()

如果视口总是强制此 Scrollable 的宽度与视口宽度匹配，则返回 true。例如，支持换行的正常文本视图在这里将返回 true，因为不希望让换行内容超出视口右边界而无法显示。注意，其祖先为 JScrollPane 的 Scrollable 返回 true 可有效地禁用水平滚动。

类似于 JViewport 的滚动容器在每次进行验证时都将使用此方法。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportWidth

返回：

如果视口应该强制 Scrollable 宽度与其自身宽度相匹配，则返回 true

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()

如果视口总是强制此 Scrollable 的高度与视口高度匹配，则返回 true。例如，纵行文本视图（按列从左向右流入文本）通过在此处返回 true 可有效地禁用垂直滚动。

类似于 JViewport 的滚动容器在每次进行验证时都将使用此方法。

指定者：

接口 Scrollable 中的 getScrollableTracksViewportHeight

返回：

如果视口强制 Scrollable 高度与其自身高度匹配，则返回 true

print

public boolean print()
              throws PrinterException

一个便捷打印方法，它显示打印对话框，然后在交互 模式下打印此 JTextComponent，不打印标题和脚注文本。注：打印完成前此方法将阻塞。

注：在 headless 模式下，不显示对话框。

此方法调用功能完备的 print 方法执行打印。

返回：

除非用户取消了打印，否则返回 true

抛出：

PrinterException - 如果打印系统中发生导致打印中断的错误

SecurityException - 如果不允许此线程初始化打印作业请求

从以下版本开始：

1.6

另请参见：

print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean)

print

public boolean print(MessageFormat headerFormat,
                     MessageFormat footerFormat)
              throws PrinterException

一个便捷打印方法，它显示打印对话框，然后在交互 模式下打印此 JTextComponent，打印指定的标题和脚注文本。注:打印完成前此方法将阻塞。

注：在 headless 模式下，不显示对话框。

此方法调用功能完备的 print 方法执行打印。

参数：

headerFormat - 在 MessageFormat 中用作标题的文本，或者为 null，表示没有标题

footerFormat - 在 MessageFormat 中用作脚注的文本，或者为 null，表示没有脚注

返回：

除非用户取消了打印，否则返回 true

抛出：

PrinterException - 如果打印系统中发生导致作业中断的错误

SecurityException - 如果不允许此线程初始化打印作业请求

从以下版本开始：

1.6

另请参见：

print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean), MessageFormat

print

public boolean print(MessageFormat headerFormat,
                     MessageFormat footerFormat,
                     boolean showPrintDialog,
                     PrintService service,
                     PrintRequestAttributeSet attributes,
                     boolean interactive)
              throws PrinterException

打印此 JTextComponent 的内容。注：打印完成前此方法将阻塞。

通过提供 MessageFormat 参数可以将页面标题和脚注文本添加到输出。打印代码从格式中请求 String，提供可能包含于格式化字符串中的单个项：表示当前页数的 Integer。

showPrintDialog boolean 参数允许指定是否向用户显示打印对话框。当向用户显示对话框时，用户可以使用该对话框更改打印属性甚至取消打印。

service 允许为打印对话框提供初始 PrintService；不显示对话框时，允许指定要打印到的 PrintService。

attributes 可用于为打印对话框提供初始值；不显示对话框时，用于提供所有需要的属性。attributes 可用于控制如何打印作业，例如双面 或单面。

interactive boolean 参数允许指定是否在交互 模式下执行打印。如果为 true，则在打印期间显示进度对话框（带有中止选项）。在事件指派线程 上调用 print 时，此对话框为有模式的，否则为无模式的。警告：打印完成前在事件指派线程 上调用此方法（其中 interactive false）将阻塞所有 事件（包括重绘）的处理。建议只有在不具有可见 GUI 的应用程序进行打印时才这样做。

注：在 headless 模式下，忽略 showPrintDialog 和 interactive 参数且不显示对话框。

此方法确保在打印期间不改变 document。要直观地指示它，则在打印期间设置 setEnabled(false)。

此方法使用 getPrintable(java.text.MessageFormat, java.text.MessageFormat) 呈现文档内容。

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

示例用法。此代码片断显示了一个跨平台的打印对话框，除非用户取消该对话框，否则在交互 模式下打印 JTextComponent：

 textComponent.print(new MessageFormat("My text component header"),
     new MessageFormat("Footer. Page - {0}"), true, null, null, true);
 

在事件指派线程 之外执行此代码将在后台 执行打印。以下模式可用于后台 打印：

     FutureTask<Boolean> future =
         new FutureTask<Boolean>(
             new Callable<Boolean>() {
                 public Boolean call() {
                     return textComponent.print(.....);
                 }  
             });
     executor.execute(future);
 

参数：

headerFormat - 在 MessageFormat 中用作标题的文本，或者为 null，表示没有标题

footerFormat - 在 MessageFormat 中用作脚注的文本，或者为 null，表示没有脚注

showPrintDialog - 如果显示打印对话框，则为 true，否则为 false

service - 初始 PrintService，或者为 null，表示使用默认值

attributes - 应用于打印作业的作业属性，或者为 null，表示没有作业属性

interactive - 是否在交互模式下进行打印

返回：

除非用户取消了打印，否则返回 true

抛出：

PrinterException - 如果打印系统中发生了导致作业中断的错误

SecurityException - 如果不允许此线程初始化打印作业请求

从以下版本开始：

1.6

另请参见：

getPrintable(java.text.MessageFormat, java.text.MessageFormat), MessageFormat, GraphicsEnvironment.isHeadless(), FutureTask

getPrintable

public Printable getPrintable(MessageFormat headerFormat,
                              MessageFormat footerFormat)

返回一个 Printable，用于打印此 JTextComponent 的内容。返回的 Printable 以文档在屏幕上呈现的外形对该文档进行打印，为了符合纸张标准重新格式化时除外。返回的 Printable 可包装于另一个 Printable 内，以便创建复杂的报告和文档。

返回的 Printable 与此 JTextComponent 共享 document。开发人员确保使用此 Printable 时不改变 document。打印期间改变 document 将导致不确定的打印行为。

通过提供 MessageFormat 参数可以将页面标题和脚注文本添加到输出。打印代码从格式中请求 String，提供可能包含于格式化字符串中的单个项：表示当前页数的 Integer。

打印时，返回的 Printable 对文档内容进行适当地格式化以适合页面大小。为了能正确的自动换行，所有页面的 imageable width 必须相同。请参阅 PageFormat.getImageableWidth()。

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

可以在任意线程上打印返回的 Printable。

返回 Printable 的此实现在事件指派线程 上执行所有打印，而不管是在什么线程上使用它。

参数：

headerFormat - 在 MessageFormat 中用作标题的文本，或者为 null，表示没有标题

footerFormat - 在 MessageFormat 中用作脚注的文本，或者为 null，表示没有脚注

返回：

打印此 JTextComponent 内容时使用的 Printable

从以下版本开始：

1.6

另请参见：

Printable, PageFormat, Document.render(java.lang.Runnable)

getAccessibleContext

public AccessibleContext getAccessibleContext()

获取与此 JTextComponent 关联的 AccessibleContext。对于文本组件，AccessibleContext 采用 AccessibleJTextComponent 的形式。如有必要，可以创建一个新的 AccessibleJTextComponent 实例。

指定者：

接口 Accessible 中的 getAccessibleContext

覆盖：

类 JComponent 中的 getAccessibleContext

返回：

充当此 JTextComponent 的 AccessibleContext 的 AccessibleJTextComponent

paramString

protected String paramString()

返回此 JTextComponent 的字符串表示形式。此方法仅在进行调试的时候使用，返回的字符串的内容和格式在各种实现间可能有所不同。返回的字符串可以为空，但不可以为 null。

重写 paramString 来提供有关 JFC 组件的一些特定新方面的信息。

覆盖：

类 JComponent 中的 paramString

返回：

此 JTextComponent 的字符串表示形式

processInputMethodEvent

protected void processInputMethodEvent(InputMethodEvent e)

从类 Component 复制的描述

处理组件上发生的输入方法事件，方法是将其指派到任意已注册的 InputMethodListener 对象。

如果组件上没有启用输入方法事件，则不调用此方法。发生下列之一时启用输入方法事件：

• 通过 addInputMethodListener 注册了一个 InputMethodListener 对象。
• 通过 enableEvents 启用了输入方法事件。

注意，如果事件参数为 null，则未指定行为并且可能导致异常。

覆盖：

类 Component 中的 processInputMethodEvent

参数：

e - 输入方法事件

另请参见：

InputMethodEvent, InputMethodListener, Component.addInputMethodListener(java.awt.event.InputMethodListener), Component.enableEvents(long)

getInputMethodRequests

public InputMethodRequests getInputMethodRequests()

从类 Component 复制的描述

获取输入方法请求处理程序，该处理程序支持此组件输入方法发出的请求。支持当场文本输入的组件必须重写此方法，以便返回一个 InputMethodRequests 实例。同时，还必须处理输入方法事件。

覆盖：

类 Component 中的 getInputMethodRequests

返回：

组件的输入方法请求处理程序，默认为 null

另请参见：

Component.addInputMethodListener(java.awt.event.InputMethodListener)

addInputMethodListener

public void addInputMethodListener(InputMethodListener l)

从类 Component 复制的描述

添加指定的输入方法侦听器，以接收发自此组件的输入方法事件。如果组件还重写了 getInputMethodRequests 并返回一个 InputMethodRequests 实例，则该组件只接收发自输入方法的输入方法事件。如果侦听器 l 为 null，则不会抛出异常并且不执行动作。

有关 AWT 的线程模型的细节信息，请参阅 AWT 线程问题。

覆盖：

类 Component 中的 addInputMethodListener

参数：

l - 输入方法侦听器

另请参见：

InputMethodEvent, InputMethodListener, Component.removeInputMethodListener(java.awt.event.InputMethodListener), Component.getInputMethodListeners(), Component.getInputMethodRequests()

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