-
- All Known Subinterfaces:
-
StyledDocument
- 所有已知实现类:
-
AbstractDocument
,DefaultStyledDocument
,HTMLDocument
,PlainDocument
public interface Document
Document
是用于文本的容器,用作swing文本组件的模型。 此接口的目标是从非常简单的需求(纯文本文本字段)扩展到复杂需求(例如,HTML或XML文档)。内容
在最简单的级别,文本可以建模为线性字符序列。 为了支持国际化,Swing文本模型使用unicode个字符。 文本组件中显示的字符序列通常称为组件的内容 。
要引用序列中的位置,使用的坐标是两个字符之间的位置。 如下图所示,文本文档中的位置可以称为位置或偏移。 这个位置是从零开始的。
在该示例中,如果文档的内容是序列“The quick brown fox”,如上图所示,则单词“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 。 如果通过其api对
Document
进行突变,DocumentEvent
发送到所有已注册的DocumentListeners
。 如果Document
实现支持撤消/重做功能,UndoableEditEvent
将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
-
-
字段汇总
字段 变量和类型 字段 描述 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)
如果模型支持异步更新,则允许在存在并发的情况下安全地呈现模型。
-
-
-
方法详细信息
-
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中还将包含为响应更改而插入和删除元素的详细信息。 由文档的实现来决定结构应如何响应删除而改变。
如果Document支持undo / redo,还将生成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的偏移量和长度将指示实际对Document进行的更改。如果Document结构因插入而更改,则生成的DocumentEvent中还将包含为响应更改而插入和删除Elements的详细信息。 由文档的实现决定结构应如何响应插入而改变。
如果Document支持undo / redo,还将生成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)
如果模型支持异步更新,则允许在存在并发的情况下安全地呈现模型。 给定的runnable将以允许它在执行runnable时安全地读取模型而不进行任何更改的方式执行。 可运行本身可能不会发生任何突变。- 参数
-
r
- 用于渲染模型的Runnable
-
-