documentlistener.html

来自「jsf、swing的官方指南」· HTML 代码 · 共 626 行 · 第 1/2 页

<div class="linkBHEAD"><a href="treemodellistener.html">How to Write a Tree Model Listener</a></div>
<div class="linkBHEAD"><a href="treeselectionlistener.html">How to Write a Tree Selection Listener</a></div>
<div class="linkBHEAD"><a href="treewillexpandlistener.html">How to Write a Tree-Will-Expand Listener</a></div>
<div class="linkBHEAD"><a href="undoableeditlistener.html">How to Write an Undoable Edit Listener</a></div>
<div class="linkBHEAD"><a href="windowlistener.html">How to Write Window Listeners</a></div>
<div class="linkAHEAD"><a href="api.html">Listener API Table</a></div>
<div class="linkAHEAD"><a href="problems.html">Solving Common Event-Handling Problems</a></div>
</div>
    </div>
    <div id=MainFlow class=MainFlow_indented>
            <span id=BreadCrumbs>
                <a href=../../index.html target=_top>Home Page</a>
                &gt;
                <a href=../index.html target=_top>Creating a GUI with JFC/Swing</a>
                &gt;
                <a href=index.html target=_top>Writing Event Listeners</a>
            </span>
            <div class=NavBit>
                <a target=_top href=containerlistener.html>&laquo;&nbsp;Previous</a>&nbsp;&bull;&nbsp;<a target=_top href=../TOC.html>Trail</a>&nbsp;&bull;&nbsp;<a target=_top href=focuslistener.html>Next&nbsp;&raquo;</a>
            </div>
            <div id=PageTitle>How to Write a Document Listener</div>
            <blockquote>

A Swing text component uses a
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/text/Document.html"><code>Document</code></a> to hold and edit its text.
Document events occur when the content of a document changes in any way.
You attach a document listener to a text component's document,
rather than to the text component itself.

<p><font color=red>[PENDING: Add a link to "Implementing a Document
Filter" in generaltext when it becomes available.]</font>

<p>
The following example demonstrates document events on
two plain text components.

<p><center><IMG SRC="../../figures/uiswing/events/DocumentEventDemo.png" WIDTH="414" HEIGHT="214" ALIGN="BOTTOM" ALT=""></center></p>
<p>


<blockquote><hr><strong>Try this:</strong>&nbsp;
<ol>
<li> <a href="http://java.sun.com/docs/books/tutorialJWS/uiswing/events/examples/DocumentEventDemo.jnlp">Run
     DocumentEventDemo</a> using
     <a href=http://java.sun.com/products/javawebstart>
     Java<sup><font size=-2>TM</font></sup> Web Start</a>.
     Or, to compile and run the example yourself,
     consult the
     <a href="examples/index.html#DocumentEventDemo">example index</a>.
<li> Type in the text field at the upper left of the window
     or the text area beneath the text field.
     <br>
     One document event is fired for each character typed.
<li> Delete text with the backspace key.
     <br>
     One document event is fired for each backspace key typed.
<li> Select text and then delete it by typing backspace
     or by using a keyboard command such as <code>CTRL-X</code> (cut).
     <br>
     One document event is fired for the entire deletion.
<li> Copy text from one text component into the other
     using keyboard commands such as <code>CTRL-C</code> (copy) and
     <code>CTRL-V</code> (paste).
     <br>
     One document event is fired for the entire paste
     operation regardless
     of the length of the text pasted.
     If text is selected in the target text component
     before the paste command is issued,
     an additional document event is fired
     because the selected text is deleted first.
</ol>
<hr></blockquote>

<p>

You can find the demo's code in

<a class="SourceLink" target="_blank" href="examples/DocumentEventDemo.java"><code>DocumentEventDemo.java</code></a>.
Here is the demo's document event handling code:

<blockquote><pre>
public class DocumentEventDemo ... {
    <em>...//where initialization occurs:</em>
    textField = new JTextField(20);
    textField.addActionListener(new MyTextActionListener());
    textField.getDocument().addDocumentListener(new MyDocumentListener());
    textField.getDocument().putProperty("name", "Text Field");

    textArea = new JTextArea();
    textArea.getDocument().addDocumentListener(new MyDocumentListener());
    textArea.getDocument().putProperty("name", "Text Area");
    ...

class MyDocumentListener implements DocumentListener {
    String newline = "\n";
 
    public void insertUpdate(DocumentEvent e) {
        updateLog(e, "inserted into");
    }
    public void removeUpdate(DocumentEvent e) {
        updateLog(e, "removed from");
    }
    public void changedUpdate(DocumentEvent e) {
        //Plain text components don't fire these events
    }

    public void updateLog(DocumentEvent e, String action) {
        Document doc = (Document)e.getDocument();
        int changeLength = e.getLength();
        displayArea.append(
            changeLength + " character" +
            ((changeLength == 1) ? " " : "s ") +
            action + doc.getProperty("name") + "." + newline +
            "  Text length = " + doc.getLength() + newline);
    }
}
</pre></blockquote>

Document listeners shouldn't modify the contents of the document;
The change is already complete
by the time the listener is notified of the change.
Instead, write a custom document that overrides the
<code>insertString</code> or <code>remove</code> methods, or both.
See
<a class="TutorialLink" target="_top" href="../components/generaltext.html#doclisteners">Listening for Changes on a Document</a> for details.

</blockquote>
<h3>
<a name="api">The Document Listener API</a>
</h3>
<blockquote>

<p align=center><a name="documentlistener">The DocumentListener
   Interface</a>
<p><em><code>DocumentListener</code> has no adapter class.</em>
<table border=1>
<tr>
<th align=left>Method</th>
<th align=left>Purpose</th>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentListener.html#changedUpdate(javax.swing.event.DocumentEvent)">changedUpdate(DocumentEvent)</a></td>
<td> Called when the style of some of the text in the
     listened-to document changes.
     This sort of event is fired only from a <code>StyledDocument</code> 
     &#151; a <code>PlainDocument</code> does not fire these events.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentListener.html#insertUpdate(javax.swing.event.DocumentEvent)">insertUpdate(DocumentEvent)</a></td>
<td> Called when text is inserted into the listened-to document.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentListener.html#removeUpdate(javax.swing.event.DocumentEvent)">removeUpdate(DocumentEvent)</a></td>
<td> Called when text is removed from the listened-to document.
</td>
</tr>

</table>

<p align=center><a name="documentevent">The DocumentEvent Interface</a>
<p>Each document event method is passed an object that implements
the <code>DocumentEvent</code> interface.  Typically, this is an
instance of 
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/text/AbstractDocument.DefaultDocumentEvent.html"><code>DefaultDocumentEvent</code></a>, defined in <code>AbstractDocument</code>.
<table border=1>
<tr>
<th align=left>Method</th>
<th align=left>Purpose</th>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.html#getDocument()">Document getDocument()</a></td>
<td>Returns the document that fired the event.  Note that the
    <code>DocumentEvent</code> interface does not inherit from
    <code>EventObject</code>.  Therefore, it does not inherit
    the <code>getSource</code> method.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.html#getLength()">int getLength()</a></td>
<td>Returns the length of the change.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.html#getOffset()">int getOffset()</a></td>
<td>Returns the location within the document of the first
    character changed.
</td>
</tr>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.html#getChange(javax.swing.text.Element)">ElementChange getChange(Element)</a></td>
<td>Returns details about what elements in the document have
    changed and how.
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.ElementChange.html"><code>ElementChange</code></a> is an interface defined
within the <code>DocumentEvent</code> interface.
</td>

<tr>
<td>
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.html#getType()">EventType getType()</a></td>
<td>Returns the type of change that occurred.
<a class="APILink" target="_blank" href="http://java.sun.com/javase/6/docs/api/javax/swing/event/DocumentEvent.EventType.html"><code>EventType</code></a>    is a class defined
    within the <code>DocumentEvent</code> interface
    that enumerates the possible
    changes that can occur on a document:
    insert text, remove text, and change text style.
</td>

</table>
</blockquote>

<a name="eg">
<h3>Examples that Use Document Listeners</h3>
</a>
<blockquote>
The following table lists the
examples that use document listeners.

<p>

<table>
<tr>
<th align=left> Example
</th>
<th align=left> Where Described
</th>
<th align=left> Notes

</th>
</tr>
<tr valign=top>
<td> <a href="examples/index.html#DocumentEventDemo">
     <code>DocumentEventDemo</code></a>
</td>
<td> This section
</td>
<td> Reports all document events that occur on the documents for
     both a text field and a text area.
     One listener listens to both text components and uses
     a client property on the document to determine which component
     fired the event.

</td>
</tr>

<tr valign=top>
<td> <a href="../components/examples/index.html#TextComponentDemo">
     <code>TextComponentDemo</code></a>
</td>
<td>
<a class="TutorialLink" target="_top" href="../components/generaltext.html#doclisteners">Listening for Changes on a Document</a></td>
<td> Updates a change log every time text in the listened-to document changes.
     The document in this example supports styled text,
     so <code>changedUpdate</code> gets called in this example.
     Requires this additional source file:
     <a href="../components/examples/index.html#DocumentSizeFilter">
     <code>DocumentSizeFilter</code></a>

</td>
</tr>

</table>



        </blockquote>
        <div class=NavBit>
            <a target=_top href=containerlistener.html>&laquo; Previous</a>
            &bull;
            <a target=_top href=../TOC.html>Trail</a>
            &bull;
            <a target=_top href=focuslistener.html>Next &raquo;</a>
        </div>
    </div>
    <div id=Footer>
<div id=TagNotes>
    Problems with the examples? Try <a target="_blank"
        href=../../information/run-examples.html>Compiling and Running
        the Examples: FAQs</a>.
    <br>
    Complaints? Compliments? Suggestions? <a target="_blank"
        href="http://developer.sun.com/contact/tutorial_feedback.jsp">Give
    us your feedback</a>.
<br><br>
    <a target="_blank" href="../../information/copyright.html">Copyright</a>
    1995-2006 Sun Microsystems, Inc.  All rights reserved.
    <span id=Download>
</span></div> 

    </div>
    <div class=PrintHeaders>
        <b>Previous page:</b> How to Write a Container Listener
        <br><b>Next page:</b> How to Write a Focus Listener
    </div>
    </body>
</html>