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

字段摘要

static String	StreamDescriptionProperty 用于描述初始化文档的流的属性名。
static String	TitleProperty 文档标题的属性名（如果有）。

方法摘要

void	addDocumentListener(DocumentListener listener) 注册给定的观察者以便开始接收文档发生更改的通知。
void	addUndoableEditListener(UndoableEditListener listener) 注册给定的观察者以便开始接收文档发生不可撤消的编辑的通知。
Position	createPosition(int offs) 此方法允许应用程序在字符内容序列中标记位置。
Element	getDefaultRootElement() 返回视图赖以存在的根元素，除非提供了向元素结构指定视图的其他机制。
Position	getEndPosition() 返回代表文档结束处的位置。
int	getLength() 返回文档中当前内容的字符数。
Object	getProperty(Object key) 获得与文档关联的属性。
Element[]	getRootElements() 返回定义的所有根元素。
Position	getStartPosition() 返回代表文档起始处的位置。
String	getText(int offset, int length) 获取文档中给定部分包含的文本。
void	getText(int offset, int length, Segment txt) 获取文档中给定部分包含的文本。
void	insertString(int offset, String str, AttributeSet a) 插入内容字符串。
void	putProperty(Object key, Object value) 将属性与文档关联。
void	remove(int offs, int len) 移除文档的部分内容。
void	removeDocumentListener(DocumentListener listener) 将给定的观察者从通知列表中撤消注册，这样就不再接收改动更新。
void	removeUndoableEditListener(UndoableEditListener listener) 将给定的观察者从通知列表中撤消注册，这样就不再接收更新。
void	render(Runnable r) 如果模型支持异步更新，则允许在并发情况下安全呈现模型。

字段详细信息

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)

putProperty

void putProperty(Object key,
                 Object value)

将属性与文档关联。提供两个标准属性键：StreamDescriptionProperty 和 TitleProperty。也可以定义其他属性，如 author。

参数：

key - 非 null 属性键

value - 属性值

另请参见：

getProperty(Object)

remove

void remove(int offs,
            int len)
            throws BadLocationException

移除文档的部分内容。这将导致对注册的 DocumentListener 发送类型为 DocumentEvent.EventType.REMOVE 的 DocumentEvent，除非抛出异常。通过在 DocumentListener 上调用 removeUpdate 方法，通知被发送到侦听器。

为确保并发情况下的合理行为，事件在改动发生之后指派。这意味着在指派移除通知之前，文档已经更新并且由 createPosition 创建的任何标记已更改。对于移除的情况，移除范围的结束折叠至范围的开始，移除范围内的任何标记都折叠至范围的开始。

如果移除导致 Document 结构更改，生成的 DocumentEvent 中还将包含更改所涉及的插入和移除 Element 的细节。移除对结构造成的更改则具体取决于 Document 的实现。

如果 Document 支持撤消/重复，还将生成 UndoableEditEvent。

参数：

offs - 起始位置的偏移量，该值 >= 0

len - 要移除的字符数，该值 >= 0

抛出：

BadLocationException - 移除范围的有些部分不是文档的有效部分。异常中的位置为遇到的第一个损坏位置。

另请参见：

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

void insertString(int offset,
                  String str,
                  AttributeSet a)
                  throws BadLocationException

插入内容字符串。这将导致对注册的 DocumentListener 发送类型为 DocumentEvent.EventType.INSERT 的 DocumentEvent，除非抛出异常。通过在 DocumentListener 上调用 insertUpdate 方法传送 DocumentEvent。生成的 DocumentEvent 的偏移量和长度将指示对 Document 实际进行的更改。

如果插入导致 Document 结构更改，有关更改涉及的插入和移除的 Element 的细节将包含在生成的 DocumentEvent 中。作为对插入的响应，由 Document 的实现决定结构应如何更改。

如果 Document 支持撤消/重复，还将生成 UndoableEditEvent。

参数：

offset - 要插入内容的偏移量，该值 >= 0。跟踪给定的位置或其后位置的更改的所有位置都将移动。

str - 要插入的字符串

a - 要与插入的内容关联的属性。如果没有属性，它可能为 null。

抛出：

BadLocationException - 给定插入位置不是文档中的有效位置

另请参见：

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

getText

String getText(int offset,
               int length)
               throws BadLocationException

获取文档中给定部分包含的文本。

参数：

offset - 文档中代表所需文本起始位置的偏移量，该值 >= 0

length - 需要的字符串的长度，该值 >= 0

返回：

以长度 >= 0 的字符串形式返回文本。

抛出：

BadLocationException - 给定范围的某些部分不是文档中的有效部分。异常中的位置为遇到的第一个损坏位置。

getText

void getText(int offset,
             int length,
             Segment txt)
             throws BadLocationException

获取文档中给定部分包含的文本。

如果 txt 参数的 partialReturn 属性为 false，Segment 中返回的数据将是请求的整个长度，根据数据存储的方式可能是副本，也可能不是。如果 partialReturn 属性为 true，则只返回不需要创建副本即能返回的文本量。使用部分返回在需要扫描大部分文档的情况下具有更好的效果。下面是使用部分返回访问整个文档的示例：

   int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);   
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do someting with text
       nleft -= text.count;
       offs += text.count;
   }

 

参数：

offset - 文档中代表所需文本起始位置的偏移量，该值 >= 0

length - 需要的字符串的长度，该值 >= 0

txt - 要在其中返回文本的 Segment 对象

抛出：

BadLocationException - 给定范围的某些部分不是文档中的有效部分。异常中的位置为遇到的第一个损坏位置。

getStartPosition

Position getStartPosition()

返回代表文档起始处的位置。可对返回的位置进行计数以便跟踪更改，也可以让其保留在文档起始位置。

返回：

位置

getEndPosition

Position getEndPosition()

返回代表文档结束处的位置。可对返回的位置进行计数以便跟踪更改，也可以让其保留在文档结束位置。

返回：

位置

createPosition

Position createPosition(int offs)
                        throws BadLocationException

此方法允许应用程序在字符内容序列中标记位置。然后可使用此标记对在内容中的插入和移除的更改进行跟踪。总的策略是，总在当前位置之前插入（最常见的情况），除非插入位置为零，这种情况下强制插入到原点位置之后。

参数：

offs - 文档起始处的偏移量，该值 >= 0

返回：

位置

抛出：

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

getRootElements

Element[] getRootElements()

返回定义的所有根元素。

通常只有一个文档结构，但是此接口支持在文本数据上构建任意数的结构投影。文档可以有多个根元素以支持多文档结构。一些示例如下：

• 文本方向。
• 词法解析标记流。
• 解析树。
• 转换为本机格式以外的格式。
• 修改规范。
• 注释。

返回：

根元素

getDefaultRootElement

Element getDefaultRootElement()

返回视图赖以存在的根元素，除非提供了向元素结构指定视图的其他机制。

返回：

根元素

render

void render(Runnable r)

如果模型支持异步更新，则允许在并发情况下安全呈现模型。给定的可运行程序的执行方式是，在可运行程序执行时安全读取模型且不作任何更改。可运行程序本身不 作任何改变。

参数：

r - 用于呈现模型的 Runnable