Module  java.desktop
软件包  javax.swing.text

Interface Document

  • All Known Subinterfaces:
    StyledDocument
    所有已知实现类:
    AbstractDocumentDefaultStyledDocumentHTMLDocumentPlainDocument


    public interface Document

    Document是用于文本的容器,用作挥杆文本组件的模型。 该接口的目标是从非常简单的需求(纯文本字段)扩展到复杂的需求(例如,HTML或XML文档)。

    内容

    在最简单的层面上,文本可以被建模为一个线性的字符序列。 为了支持国际化,Swing文本模型使用unicode个字符。 文本组件中显示的字符序列通常称为组件的内容

    要引用序列中的位置,所使用的坐标是两个字符之间的位置。 如下图所示,文本文档中的位置可以称为位置或偏移。 这个位置是基于零的。

    以下文字描述了此图形。

    在这个例子中,如上图所示,如果文档的内容是序列“快速棕色狐狸”,则位于“The”之前的位置为0,位于“The”之后的位置后面的空格是3。序列“The”中的整个字符序列被称为范围

    以下方法可以访问构成内容的字符数据。

    结构体

    文本很少被简单地表示为无特征的内容。 相反,文本通常具有与其相关联的某种结构。 正是由什么结构建模到由一个特定的Document实现。 它可能就像没有结构一样简单(即一个简单的文本字段),或者它可能是如下图所示。

    图 - >章 - >段

    结构单元(即树的一个节点)由Element接口引用 每个元素都可以用一组属性标记。 这些属性(名称/值对)由AttributeSet界面定义。

    以下方法可以访问文档结构。

    突变

    所有文件需要能够添加和删除简单文本。 通常,通过手势从键盘或鼠标插入和删除文本。 对文档结构的插入或删除有什么影响完全取决于文档的实现。

    以下方法与文件内容的突变有关:

    通知

    Document必须传达给感兴趣的观察员。 更改通知遵循为JavaBeans指定的事件模型指南。 在JavaBeans事件模型中,一旦调度了事件通知,在事件源发生任何进一步突变之前,必须通知所有侦听器。 此外,交货的顺序不能保证。

    通知作为两个单独的事件提供, DocumentEventUndoableEditEvent 如果一个突变的制作Document通过其API,一个DocumentEvent将被发送到所有注册的DocumentListeners 如果Document实现支持撤销/重做功能,则UndoableEditEvent将被发送到所有注册的UndoableEditListener 如果可撤销的编辑被撤销,则应从文档中触发一个DocumentEvent以指示它已重新更改。 然而,在这种情况下,应该不会生成UndoableEditEvent因为编辑实际上是变化的根源,而不是通过其api进行的Document的突变。

    前面的文字描述了这个图形。

    参考上图,假设左侧所示的组件会以蓝色矩形表示的文档对象进行变异。 该文档通过将DocumentEvent分派到两个组件视图进行响应,并将一个UndoableEditEvent发送到监听逻辑,该监听逻辑维护一个历史缓冲区。

    现在假设右侧显示的组件会将相同的文档变为同一文档。 同样,文档会将DocumentEvent分派到两个组件视图,并将UndoableEditEvent发送到维护历史缓冲区的侦听逻辑。

    如果历史记录缓冲区然后回滚(即最后一个UndoableEdit撤消),则会将一个DocumentEvent发送到这两个视图,这两个视图都会将文档中的撤消变量反映出来(也就是删除正确的组件的突变)。 如果历史缓冲区再次回滚另一个更改,则会将另一个DocumentEvent发送到这两个视图,从而使它们反映到文档的撤消变量 - 即删除左组件的突变。

    与文献观察突变有关的方法有:

    属性

    文档实现通常会在运行时具有与它们相关联的一些属性集。 两个众所周知的属性是StreamDescriptionProperty ,可以用来描述Document来自哪里,而TitleProperty可以用来命名Document 与属性相关的方法有:

    有关Document课程的更多信息,请参阅The Swing Connection ,特别是文章The Element Interface

    另请参见:
    DocumentEventDocumentListenerUndoableEditEventUndoableEditListenerElementPositionAttributeSet
    • 字段详细信息

      • StreamDescriptionProperty

        static final String StreamDescriptionProperty
        用于初始化文档的流的描述的属性名称。 如果文档是从流初始化的,并且关于流的所有内容都是已知的,则应该使用这一点。
        另请参见:
        Constant Field Values
      • TitleProperty

        static final String TitleProperty
        文件标题的属性名称,如果有的话。
        另请参见:
        Constant Field Values
    • 方法详细信息

      • getLength

        int getLength​()
        返回文档中当前内容的字符数。
        结果
        字符数> = 0
      • addUndoableEditListener

        void addUndoableEditListener​(UndoableEditListener listener)
        注册给定的观察者,以便在对文档进行撤消修改时开始接收通知。
        参数
        listener - 观察员注册
        另请参见:
        UndoableEditEvent
      • removeUndoableEditListener

        void removeUndoableEditListener​(UndoableEditListener listener)
        从通知列表中注销给定的观察者,因此它将不再接收更新。
        参数
        listener - 观察员注册
        另请参见:
        UndoableEditEvent
      • remove

        void remove​(int offs,
                    int len)
             throws BadLocationException
        删除文档内容的一部分。 这将导致DocumentEvent.EventType.REMOVE类型的DocumentEvent发送到已注册的DocumentListeners,除非抛出异常。 该通知将通过调用DocumentListeners上的removeUpdate方法发送给监听器。

        为了确保在并发性方面的合理行为,事件发生后发生。 这意味着在发送删除通知之后,文档已经被更新,并且由createPosition创建的任何标记已经改变。 对于删除,删除范围的结束将折叠到范围的开始,并且删除范围中的任何标记都将折叠到范围的开头。

        图表显示从“快速棕色狐狸”中删除“快速”。

        如果文档结构由于删除而更改,则会在生成的DocumentEvent中包含要更改的元素插入和删除的详细信息。 由文件的实施决定结构如何改变以应对删除。

        如果文档支持撤消/重做,则还将生成UndoableEditEvent。

        参数
        offs - 从开始> = 0的偏移量
        len - 要删除的字符数> = 0
        异常
        BadLocationException - 删除范围的某些部分不是文档的有效部分。 异常中的位置是遇到的第一个坏位置。
        另请参见:
        DocumentEventDocumentListenerUndoableEditEventUndoableEditListener
      • 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 - 给定的插入位置不是文档中的有效位置
        另请参见:
        DocumentEventDocumentListenerUndoableEditEventUndoableEditListener
      • 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