-
- All Known Subinterfaces:
-
StyledDocument
- 所有已知实现类:
-
AbstractDocument
,DefaultStyledDocument
,HTMLDocument
,PlainDocument
public interface Document
Document
是用于文本的容器,用作挥杆文本组件的模型。 该接口的目标是从非常简单的需求(纯文本字段)扩展到复杂的需求(例如,HTML或XML文档)。内容
在最简单的层面上,文本可以被建模为一个线性的字符序列。 为了支持国际化,Swing文本模型使用unicode个字符。 文本组件中显示的字符序列通常称为组件的内容 。
要引用序列中的位置,所使用的坐标是两个字符之间的位置。 如下图所示,文本文档中的位置可以称为位置或偏移。 这个位置是基于零的。
在这个例子中,如上图所示,如果文档的内容是序列“快速棕色狐狸”,则位于“The”之前的位置为0,位于“The”之后的位置后面的空格是3。序列“The”中的整个字符序列被称为范围 。
以下方法可以访问构成内容的字符数据。
结构体
文本很少被简单地表示为无特征的内容。 相反,文本通常具有与其相关联的某种结构。 正是由什么结构建模到由一个特定的Document实现。 它可能就像没有结构一样简单(即一个简单的文本字段),或者它可能是如下图所示。
结构单元(即树的一个节点)由Element接口引用 。 每个元素都可以用一组属性标记。 这些属性(名称/值对)由AttributeSet界面定义。
以下方法可以访问文档结构。
突变
所有文件需要能够添加和删除简单文本。 通常,通过手势从键盘或鼠标插入和删除文本。 对文档结构的插入或删除有什么影响完全取决于文档的实现。
以下方法与文件内容的突变有关:
-
insertString(int, java.lang.String, javax.swing.text.AttributeSet)
-
remove(int, int)
-
createPosition(int)
通知
Document
必须传达给感兴趣的观察员。 更改通知遵循为JavaBeans指定的事件模型指南。 在JavaBeans事件模型中,一旦调度了事件通知,在事件源发生任何进一步突变之前,必须通知所有侦听器。 此外,交货的顺序不能保证。通知作为两个单独的事件提供, DocumentEvent和UndoableEditEvent 。 如果一个突变的制作
Document
通过其API,一个DocumentEvent
将被发送到所有注册的DocumentListeners
。 如果Document
实现支持撤销/重做功能,则UndoableEditEvent
将被发送到所有注册的UndoableEditListener
。 如果可撤销的编辑被撤销,则应从文档中触发一个DocumentEvent
以指示它已重新更改。 然而,在这种情况下,应该不会生成UndoableEditEvent
因为编辑实际上是变化的根源,而不是通过其api进行的Document
的突变。参考上图,假设左侧所示的组件会以蓝色矩形表示的文档对象进行变异。 该文档通过将DocumentEvent分派到两个组件视图进行响应,并将一个UndoableEditEvent发送到监听逻辑,该监听逻辑维护一个历史缓冲区。
现在假设右侧显示的组件会将相同的文档变为同一文档。 同样,文档会将DocumentEvent分派到两个组件视图,并将UndoableEditEvent发送到维护历史缓冲区的侦听逻辑。
如果历史记录缓冲区然后回滚(即最后一个UndoableEdit撤消),则会将一个DocumentEvent发送到这两个视图,这两个视图都会将文档中的撤消变量反映出来(也就是删除正确的组件的突变)。 如果历史缓冲区再次回滚另一个更改,则会将另一个DocumentEvent发送到这两个视图,从而使它们反映到文档的撤消变量 - 即删除左组件的突变。
与文献观察突变有关的方法有:
- addDocumentListener(DocumentListener)
- removeDocumentListener(DocumentListener)
- addUndoableEditListener(UndoableEditListener)
- removeUndoableEditListener(UndoableEditListener)
属性
文档实现通常会在运行时具有与它们相关联的一些属性集。 两个众所周知的属性是StreamDescriptionProperty ,可以用来描述
Document
来自哪里,而TitleProperty可以用来命名Document
。 与属性相关的方法有:有关
Document
课程的更多信息,请参阅The Swing Connection ,特别是文章The Element Interface 。- 另请参见:
-
DocumentEvent
,DocumentListener
,UndoableEditEvent
,UndoableEditListener
,Element
,Position
,AttributeSet
-
-
Field Summary
Fields Modifier and Type Field 描述 static String
StreamDescriptionProperty
用于初始化文档的流的描述的属性名称。static String
TitleProperty
文件标题的属性名称,如果有的话。
-
方法摘要
所有方法 接口方法 抽象方法 Modifier and Type 方法 描述 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
用于初始化文档的流的描述的属性名称。 如果文档是从流初始化的,并且关于流的所有内容都是已知的,则应该使用这一点。- 另请参见:
- Constant Field Values
-
TitleProperty
static final String TitleProperty
文件标题的属性名称,如果有的话。- 另请参见:
- Constant Field Values
-
-
方法详细信息
-
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)
- 参数
-
key
- 非null
属性键 -
value
- 属性值 - 另请参见:
-
getProperty(Object)
-
remove
void remove(int offs, int len) throws BadLocationException
删除文档内容的一部分。 这将导致DocumentEvent.EventType.REMOVE类型的DocumentEvent发送到已注册的DocumentListeners,除非抛出异常。 该通知将通过调用DocumentListeners上的removeUpdate方法发送给监听器。为了确保在并发性方面的合理行为,事件发生后发生。 这意味着在发送删除通知之后,文档已经被更新,并且由
createPosition
创建的任何标记已经改变。 对于删除,删除范围的结束将折叠到范围的开始,并且删除范围中的任何标记都将折叠到范围的开头。如果文档结构由于删除而更改,则会在生成的DocumentEvent中包含要更改的元素插入和删除的详细信息。 由文件的实施决定结构如何改变以应对删除。
如果文档支持撤消/重做,则还将生成UndoableEditEvent。
- 参数
-
offs
- 从开始> = 0的偏移量 -
len
- 要删除的字符数> = 0 - 异常
-
BadLocationException
- 删除范围的某些部分不是文档的有效部分。 异常中的位置是遇到的第一个坏位置。 - 另请参见:
-
DocumentEvent
,DocumentListener
,UndoableEditEvent
,UndoableEditListener
-
insertString
void insertString(int offset, String str, AttributeSet a) throws BadLocationException
插入一串内容。 这将导致DocumentEvent.EventType.INSERT类型的DocumentEvent被发送到已注册的DocumentListers,除非抛出异常。 DocumentEvent将通过在DocumentListener上调用insertUpdate方法来传递。 生成的DocumentEvent的偏移量和长度将指示实际对文档进行了哪些更改。如果文档结构因插入而更改,则会在生成的DocumentEvent中包含元素插入和删除以响应更改的详细信息。 文件的执行取决于结构如何响应插入而改变。
如果文档支持撤消/重做,则还将生成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,则在段中返回的数据将是所请求的整个长度,并且根据数据的存储方式可以复制或不复制。 如果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)
如果模型支持异步更新,则允许在存在并发性的情况下安全地呈现模型。 给定的可运行程序将以允许其在执行runnable时不改变的情况下安全地读取模型的方式执行。 runnable本身可能不会发生任何突变。- 参数
-
r
- 用于渲染模型的Runnable
-
-