Document - [ Java参考文档 ] - 在线原生手册

目录搜索

文字

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

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 创建的任何标记已更改。对于移除的情况，移除范围的结束折叠至范围的开始，移除范围内的任何标记都折叠至范围的开始。

图示从 'The quick brown fox' 中移除 'quick'。

如果移除导致 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 实际进行的更改。

图示将 'quick' 插入 'The quick brown fox'

如果插入导致 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

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

javax.swing.text 接口 Document

StreamDescriptionProperty

TitleProperty

getLength

addDocumentListener

removeDocumentListener

addUndoableEditListener

removeUndoableEditListener

getProperty

putProperty

remove

insertString

getText

getText

getStartPosition

getEndPosition

createPosition

getRootElements

getDefaultRootElement

render

javax.swing.text
接口 Document