Java javax.swing.text 接口 Document（JDK5）

所有类

javax.swing.text
接口 Document

所有已知子接口：

StyledDocument

所有已知实现类：

AbstractDocument, DefaultStyledDocument, HTMLDocument, PlainDocument

public interface Document

Document 是一个作为 swing 文本组件模型的文本容器。此接口的目标是为了满足不同的文档处理需要，从非常简单的文档（纯文本 textfield）到非常复杂的文档（例如，HTML 或 XML 文档）。

内容

在最简单的级别，文本可用一个线性的字符序列模型表示。为支持国际化，Swing 文本模型使用 unicode 字符。显示在文本组件中的字符序列一般称为组件的内容。

要引用序列中的位置，使用的是两个字符之间的坐标。如下图所示，文本文档中位置可称为一个位置或一个偏移量。位置是从零开始的。

此例中，如前图所示，如果文档的内容为序列 "The quick brown fox" ，"The" 之前的位置为 0，位于 "The" 之后、它后面的空白之前的位置为 3。序列 "The" 中的整个字符序列称为一个范围。

下列方法提供对组成内容的字符数据的访问。

• getLength()
• getText(int, int)
• getText(int, int, Segment)

结构

只将文本表示为一般的内容并不常见。更多的情况下，文本都通常具有与其关联的某种结构。具体构造成哪种结构取决于特定的 Document 实现。它可以简单到没有结构（即简单的文本字段），也可以是类似下面的图。

结构单位（即树的节点）由 Element 接口引用。每个 Element 都可用一组属性标记。这些属性（名称/值对）由 AttributeSet 接口定义。

下面的方法提供对文档结构的访问。

• getDefaultRootElement
• getRootElements

可变

所有的文档都需要能够添加和移除简单的文本。通常，通过键盘或鼠标动作添加和移除文本。插入和移除对文档结构有何影响完全取决于文档的实现。

下列方法与文档内容的变化相关：

• insertString(int, String, AttributeSet)
• remove(int, int)
• createPosition(int)

通知

Document 的改变必须传送给相关的观察者。更改通知遵守为 JavaBeans 指定的事件模型大纲。在 JavaBeans 事件模型中，一旦指派了一个事件通知，必须在事件源发生进一步的更改之前通知所有的侦听器。此外，无法保证传送的顺序。

通知以两个独立的事件提供，DocumentEvent 和 UndoableEditEvent。如果通过 Document 的 api 对其进行改变，将对所有注册的 DocumentListeners 发送一个 DocumentEvent。如果 Document 实现支持撤消/重复功能，UndoableEditEvent 将发送到所有注册的 UndoableEditListener 上。如果对可撤消的编辑进行撤消，应从 Document 触发 DocumentEvent 以指示又进行了更改。但是这种情况下不应生成任何 UndoableEditEvent，因为编辑实际上是更改的源，而不是通过其 api 对 Document 进行的改变。

上图中假设左面显示的组件改变了蓝色矩形表示的文本对象。文档通过对两个组件视图指派 DocumentEvent 进行响应，并向侦听逻辑发送 UndoableEditEvent，以保留历史缓冲区。

现在假定右面显示的组件改变相同的文档。同样，文档对两个组件视图指派 DocumentEvent 并对保留历史缓冲区的侦听逻辑发送 UndoableEditEvent。

如果历史缓冲区因此回滚（即撤消上一个 UndoableEdit），将对两个视图发送 DocumentEvent，导致二者都反映出对文档的撤消改动（即移除右面的组件的改动）。如果历史缓冲区再次回滚另一个更改，将对两个视图发送另外的 DocumentEvent，导致它们反映出对文档的撤消改动，即移除左面的组件的改动。

与观察文档的改动相关的方法有：

• addDocumentListener(DocumentListener)
• removeDocumentListener(DocumentListener)
• addUndoableEditListener(UndoableEditListener)
• removeUndoableEditListener(UndoableEditListener)

属性

文档实现通常具有在运行时与之关联的某组属性。两个最常见的属性是 StreamDescriptionProperty 和 TitleProperty，前者可描述 Document 的来源，后者可用于命名 Document。与这些属性相关的方法有：

• getProperty(Object)
• putProperty(Object, Object)

有关 Document 类的更多信息，请参阅 The Swing Connection 以及更有针对性的文章 The Element Interface。

另请参见：

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener, Element, Position, AttributeSet

StreamDescriptionProperty

static final String StreamDescriptionProperty

用于描述初始化文档的流的属性名。如果文档从流初始化并且有来自该流的信息，则应使用此属性。

另请参见：

常量字段值

TitleProperty

static final String TitleProperty

文档标题的属性名（如果有）。

另请参见：

常量字段值

getLength

int getLength()

返回文档中当前内容的字符数。

返回：

字符的数量，该数量 >= 0

addDocumentListener

void addDocumentListener(DocumentListener listener)

注册给定的观察者以便开始接收文档发生更改的通知。

参数：

listener - 要注册的观察者

另请参见：

removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

void removeDocumentListener(DocumentListener listener)

将给定的观察者从通知列表中撤消注册，这样就不再接收改动更新。

参数：

listener - 要注册的观察者

另请参见：

addDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

void addUndoableEditListener(UndoableEditListener listener)

注册给定的观察者以便开始接收文档发生不可撤消的编辑的通知。

参数：

listener - 要注册的观察者

另请参见：

UndoableEditEvent

removeUndoableEditListener

void removeUndoableEditListener(UndoableEditListener listener)

将给定的观察者从通知列表中撤消注册，这样就不再接收更新。

参数：

listener - 要注册的观察者

另请参见：

UndoableEditEvent

getProperty

Object getProperty(Object key)

获得与文档关联的属性。

参数：

key - 非 null 属性键

返回：

属性

另请参见：

putProperty(Object, Object)