javax.swing.text

接口
异常
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 键移除内容。
  • 前后移动的插入符

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

该图表显示控制器、文档、事件和 ViewFactory 之间的交互

该模型由 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 包中添加了支持所有 JavaBeansTM 长期存储的功能。请参见 XMLEncoder

另请参见:
Document, DocumentEvent, DocumentListener, Caret, CaretEvent, CaretListener, TextUI, View, ViewFactory

嵌套类摘要
 class JTextComponent.AccessibleJTextComponent
          此类实现 JTextComponent 类的可访问性支持。
static class JTextComponent.DropLocation
          表示 JTextComponent 的放置位置 (drop location)。
static class JTextComponent.KeyBinding
          用于创建键绑定的绑定记录。
 
从类 javax.swing.JComponent 继承的嵌套类/接口
JComponent.AccessibleJComponent
 
从类 java.awt.Container 继承的嵌套类/接口
Container.AccessibleAWTContainer
 
从类 java.awt.Component 继承的嵌套类/接口
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
字段摘要
static String DEFAULT_KEYMAP
          将由所有 JTextComponent 实例共享的默认 keymap,除非这些实例已有另一个 keymap 集合。
static String FOCUS_ACCELERATOR_KEY
          焦点加速键的绑定 (bound) 属性名称。
 
从类 javax.swing.JComponent 继承的字段
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
从类 java.awt.Component 继承的字段
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
从接口 java.awt.image.ImageObserver 继承的字段
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
构造方法摘要
JTextComponent()
          创建一个新的 JTextComponent
 
方法摘要
 void addCaretListener(CaretListener listener)
          添加插入符侦听器,以便侦听任何插入符的更改通知。
 void addInputMethodListener(InputMethodListener l)
          添加指定的输入方法侦听器,以接收发自此组件的输入方法事件。
static Keymap addKeymap(String nm, Keymap parent)
          将一个新 keymap 添加到 keymap 层次结构。
 void copy()
          将关联文本模型中当前选定的范围传输到系统剪贴板,并在文本模型中保留内容。
 void cut()
          将关联文本模型中当前选定的范围传输到系统剪贴板,并从模型中移除内容。
protected  void fireCaretUpdate(CaretEvent e)
          通知所有已注册需要此事件类型的通知的侦听器。
 AccessibleContext getAccessibleContext()
          获取与此 JTextComponent 关联的 AccessibleContext
 Action[] getActions()
          获取编辑器的命令列表。
 Caret getCaret()
          获取允许在视图上进行面向文本导航的插入符。
 Color getCaretColor()
          获取用于呈现插入符的当前颜色。
 CaretListener[] getCaretListeners()
          返回在此文本组件上已注册的所有插入符侦听器的数组。
 int getCaretPosition()
          返回文本组件的文本插入符的位置。
 Color getDisabledTextColor()
          获取用于呈现禁用文本的当前颜色。
 Document getDocument()
          获取与编辑器关联的模型。
 boolean getDragEnabled()
          返回是否启用自动拖动处理。
 JTextComponent.DropLocation getDropLocation()
          返回在组件上进行 DnD 操作过程中此组件在视觉上指示为放置位置的位置;如果当前没有显示任何位置,则返回 null
 DropMode getDropMode()
          返回此组件的放置模式。
 char getFocusAccelerator()
          返回将导致接收文本组件获取焦点的加速键。
 Highlighter getHighlighter()
          获取负责进行高亮显示的对象。
 InputMethodRequests getInputMethodRequests()
          获取输入方法请求处理程序,该处理程序支持此组件输入方法发出的请求。
 Keymap getKeymap()
          获取当前在此文本组件中活动的 keymap。
static Keymap getKeymap(String nm)
          获取以前添加到文档中的已命名 keymap。
 Insets getMargin()
          返回文本组件的边框和它的文本之间的空白。
 NavigationFilter getNavigationFilter()
          返回 NavigationFilter
 Dimension getPreferredScrollableViewportSize()
          返回视图组件视口的首选大小。
 Printable getPrintable(MessageFormat headerFormat, MessageFormat footerFormat)
          返回一个 Printable,用于打印此 JTextComponent 的内容。
 int getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction)
          显示逻辑行或列的组件应计算滚动增量,它将根据方向的值完全公开一个行块或列块。
 boolean getScrollableTracksViewportHeight()
          如果视口总是强制此 Scrollable 的高度与视口高度匹配,则返回 true。
 boolean getScrollableTracksViewportWidth()
          如果视口总是强制此 Scrollable 的宽度与视口宽度匹配,则返回 true。
 int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction)
          显示逻辑行或列的组件应计算滚动增量,它将根据方向的值完全公开一个新的行或列。
 String getSelectedText()
          返回此 TextComponent 中包含的选定文本。
 Color getSelectedTextColor()
          获取用于呈现选定文本的当前颜色。
 Color getSelectionColor()
          获取用于呈现选定的当前颜色。
 int getSelectionEnd()
          返回选定文本的结束位置。
 int getSelectionStart()
          返回选定文本的起始位置。
 String getText()
          返回此 TextComponent 中包含的文本。
 String getText(int offs, int len)
          获取由组件表示的文本部分。
 String getToolTipText(MouseEvent event)
          返回用作 event 的工具提示的字符串。
 TextUI getUI()
          获取此面向文本的编辑器的用户界面工厂。
 boolean isEditable()
          返回指示此 TextComponent 是否可编辑的 boolean。
static void loadKeymap(Keymap map, JTextComponent.KeyBinding[] bindings, Action[] actions)
           加载带有一组绑定的 keymap。
 Rectangle modelToView(int pos)
          将模型中给定位置转换为视图坐标系统中的位置。
 void moveCaretPosition(int pos)
          将插入符移动到新的位置,同时保留最后一次调用 setCaretPosition 之前定义的标记。
protected  String paramString()
          返回此 JTextComponent 的字符串表示形式。
 void paste()
          将系统剪贴板的内容传输到关联的文本模型中。
 boolean print()
          一个便捷打印方法,它显示打印对话框,然后在交互 模式下打印此 JTextComponent,不打印标题和脚注文本。
 boolean print(MessageFormat headerFormat, MessageFormat footerFormat)
          一个便捷打印方法,它显示打印对话框,然后在交互 模式下打印此 JTextComponent,打印指定的标题和脚注文本。
 boolean print(MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintService service, PrintRequestAttributeSet attributes, boolean interactive)
          打印此 JTextComponent 的内容。
protected  void processInputMethodEvent(InputMethodEvent e)
          处理组件上发生的输入方法事件,方法是将其指派到任意已注册的 InputMethodListener 对象。
 void read(Reader in, Object desc)
          根据流进行初始化。
 void removeCaretListener(CaretListener listener)
          移除插入符侦听器。
static Keymap removeKeymap(String nm)
          移除以前添加到文档中的已命名 keymap。
 void removeNotify()
          通知此组件它不再有父组件。
 void replaceSelection(String content)
          用给定字符串所表示的新内容替换当前选定的内容。
 void select(int selectionStart, int selectionEnd)
          选定指定的开始和结束位置之间的文本。
 void selectAll()
          选择 TextComponent 中的所有文本。
 void setCaret(Caret c)
          设置要使用的插入符。
 void setCaretColor(Color c)
          设置用于呈现插入符的当前颜色。
 void setCaretPosition(int position)
          设置 TextComponent 的文本插入符的位置。
 void setComponentOrientation(ComponentOrientation o)
          设置语言敏感的方向,用于排序此组件内的元素或文本。
 void setDisabledTextColor(Color c)
          设置用于呈现禁用文本的当前颜色。
 void setDocument(Document doc)
          将编辑器与文本文档关联。
 void setDragEnabled(boolean b)
          开启或关闭自动拖动处理。
 void setDropMode(DropMode dropMode)
          设置此组件的放置模式,为了向后兼容性,此属性的默认值为 DropMode.USE_SELECTION
 void setEditable(boolean b)
          设置指定的 boolean 变量,以指示此 TextComponent 是否应该为可编辑的。
 void setFocusAccelerator(char aKey)
          设置将导致接收的文本组件获取焦点的加速键。
 void setHighlighter(Highlighter h)
          设置要使用的 highlighter。
 void setKeymap(Keymap map)
          设置用于将事件绑定到操作的 keymap。
 void setMargin(Insets m)
          设置组件的边框和它的文本之间的空白。
 void setNavigationFilter(NavigationFilter filter)
          设置 NavigationFilter
 void setSelectedTextColor(Color c)
          设置用于呈现选定文本的当前颜色。
 void setSelectionColor(Color c)
          设置用于呈现选定的当前颜色。
 void setSelectionEnd(int selectionEnd)
          将选择结束点设置为指定的位置。
 void setSelectionStart(int selectionStart)
          将选定起始点设置为指定的位置。
 void setText(String t)
          将此 TextComponent 文本设置为指定文本。
 void setUI(TextUI ui)
          设置此面向文本的编辑器的用户界面工厂。
 void updateUI()
          重新加载可插入的 UI。
 int viewToModel(Point pt)
          将视图坐标系统中的给定位置转换为模型中最具代表性的位置。
 void write(Writer out)
          将模型的内容存储到给定的流中。
 
从类 javax.swing.JComponent 继承的方法

JDK 1.6 中文手册