路径： 使用Swing创建GUI
课程： 编写事件监听器
章节： 实现常用事件的监听器

如何编写文档监听器

一个Swing文本组件使用Document来表示其内容。当文档的内容发生任何变化时，会触发文档事件。你将文档监听器附加到文本组件的文档上，而不是附加到文本组件本身上。详见实现文档过滤器了解更多信息。

下面的示例演示了两个纯文本组件上的文档事件。

试一试：

点击“启动”按钮使用Java™ Web Start运行DocumentEventDemo（下载JDK 7或更高版本）。或者，若要编译并自行运行示例，请参考示例索引。
在窗口左上方的文本字段或文本字段下方的文本区域中键入文本。
每键入一个字符，将触发一个文档事件。
使用退格键删除文本。
每按下一个退格键，将触发一个文档事件。
选择文本，然后通过键入退格键或使用CTRL-X（剪切）等键盘命令删除文本。
删除整个文本时，将触发一个文档事件。
使用CTRL-C（复制）和CTRL-V（粘贴）等键盘命令将文本从一个文本组件复制到另一个文本组件。
无论粘贴的文本长度如何，都会触发一个整个粘贴操作的文档事件。如果在执行粘贴命令之前在目标文本组件中选择了文本，则还会触发额外的文档事件，因为首先删除了选定的文本。

你可以在DocumentEventDemo.java中找到这个示例的代码。以下是示例的文档事件处理代码：

public class DocumentEventDemo ... {
    ...//初始化：
    textField = new JTextField(20);
    textField.addActionListener(new MyTextActionListener());
    textField.getDocument().addDocumentListener(new MyDocumentListener());
    textField.getDocument().putProperty("name", "文本框");

    textArea = new JTextArea();
    textArea.getDocument().addDocumentListener(new MyDocumentListener());
    textArea.getDocument().putProperty("name", "文本域");
    ...

class MyDocumentListener implements DocumentListener {
    String newline = "\n";
 
    public void insertUpdate(DocumentEvent e) {
        updateLog(e, "插入到");
    }
    public void removeUpdate(DocumentEvent e) {
        updateLog(e, "从中删除");
    }
    public void changedUpdate(DocumentEvent e) {
        //纯文本组件不会触发这些事件
    }

    public void updateLog(DocumentEvent e, String action) {
        Document doc = (Document)e.getDocument();
        int changeLength = e.getLength();
        displayArea.append(
            changeLength + "个字符" +
            ((changeLength == 1) ? " " : "s ") +
            action + doc.getProperty("name") + "." + newline +
            "  文本长度 = " + doc.getLength() + newline);
    }
}

文档监听器不应修改文档的内容；在监听器被通知到变化时，变化已经完成。相反，应编写一个自定义的文档类，重写insertString或remove方法，或两者都重写。有关详细信息，请参阅监听文档变化。

文档监听器API

文档监听器接口

DocumentListener没有适配器类。

方法	用途
changedUpdate(DocumentEvent)	当监听的文档中的某些文本的样式发生更改时调用。这种事件只从`StyledDocument`中触发，`PlainDocument`不会触发这些事件。
insertUpdate(DocumentEvent)	当文本插入到监听的文档中时调用。
removeUpdate(DocumentEvent)	当文本从监听的文档中删除时调用。

DocumentEvent接口

每个文档事件方法都传递了一个实现了DocumentEvent接口的对象。通常，这是一个AbstractDocument中定义的DefaultDocumentEvent实例。

方法	目的
Document getDocument()	返回触发事件的文档。注意，`DocumentEvent`接口没有继承`EventObject`，因此它没有继承`getSource`方法。
int getLength()	返回更改的长度。
int getOffset()	返回更改的第一个字符在文档中的位置。
ElementChange getChange(Element)	返回关于文档中哪些元素发生了更改以及如何更改的详细信息。`ElementChange`是在`DocumentEvent`接口中定义的一个接口。
EventType getType()	返回发生的更改类型。`EventType`是在`DocumentEvent`接口中定义的一个类，列举了文档上可能发生的更改类型：插入文本、删除文本和更改文本样式。

使用Document监听器的示例

以下表列出了使用Document监听器的示例。

示例	描述位置	注释
`DocumentEventDemo`	本节	报告文本字段和文本区域上发生的所有文档事件。一个监听器同时监听两个文本组件，并使用文档上的客户端属性来确定哪个组件触发了事件。
`TextComponentDemo`	监听文档变化	每当监听的文档中的文本发生变化时，更新一个变更日志。此示例中的文档支持样式文本，因此在此示例中调用`changedUpdate`方法。需要使用到另一个源文件：`DocumentSizeFilter`