模块  java.desktop
软件包  javax.swing.text

Interface Document

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

    public interface Document

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

    内容

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

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

    以下文字描述了此图形。

    在该示例中,如果文档的内容是序列“The quick brown fox”,如上图所示,则单词“The”之前的位置为0,并且单词“The”之后的位置和之前的位置它后面的空格是3.序列“The”中的整个字符序列称为范围

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

    结构体

    文本很少被简单地表示为无特征内容。 相反,文本通常具有与其相关联的某种结构。 究竟建模的结构取决于特定的Document实现。 它可能就像没有结构(即简单的文本字段)一样简单,或者它可能类似于下图。

    图表显示了Book-> Chapter-> Paragraph

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

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

    突变

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

    以下方法与文档内容的变异有关:

    通知

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

    通知作为两个单独的事件提供, DocumentEventUndoableEditEvent 如果通过其api对Document进行突变, DocumentEvent发送到所有已注册的DocumentListeners 如果Document实现支持撤消/重做功能, UndoableEditEventUndoableEditEvent发送到所有已注册的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
        用于初始化文档的流描述的属性名称。 如果从流初始化文档并且已知有关流的任何内容,则应使用此方法。
        另请参见:
        常数字段值
      • TitleProperty

        static final String TitleProperty
        文档标题的属性名称(如果有)。
        另请参见:
        常数字段值
    • 方法详细信息

      • 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中还将包含为响应更改而插入和删除元素的详细信息。 由文档的实现来决定结构应如何响应删除而改变。

        如果Document支持undo / redo,还将生成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的偏移量和长度将指示实际对Document进行的更改。

        图表显示'快速棕狐'中插入'快速'

        如果Document结构因插入而更改,则生成的DocumentEvent中还将包含为响应更改而插入和删除Elements的详细信息。 由文档的实现决定结构应如何响应插入而改变。

        如果Document支持undo / redo,还将生成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,则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