Using Components, the GUI Building Blocks

Writing a Text Listener

Text events are generated after the text in a text component has changed somehow. The 1.1 AWT components that generate text events are text fields and text areas. To get earlier notification of text changes -- for example, to intercept incorrect characters -- you should write a key listener.

Text Event Methods

The TextListener interface has just one method, so it has no corresponding adapter class. Here's the method:

void textValueChanged(TextEvent)

Called by the AWT just after the text in the listened-to component changes.

Examples of Handling Text Events

The following applet demonstrates text events. It contains two editable text components -- a text field and a text area. Pressing Return in the text field causes the field's contents to be appended to the text area. Each of the editable text components has a text listener. The two text listeners, which are both instances of a single class, append a message to an uneditable text area at the right of the applet. A button at the bottom right of the applet lets you clear the message display area.

---

Note: The above applet requires JDK 1.1. If you are using an older browser that does not support 1.1, you won't be able to run the applet. Instead, you need to view this page in a 1.1-compliant browser, such as HotJava or the JDK Applet Viewer (appletviewer).

---

---

Try this:

1. Click the text field at the upper left of the applet, then press the A character on the keyboard.
   A text event occurs, and you'll see a message in the display area at the right of the applet.
2. Type a few more characters.
   A text event occurs each time you type a character.
3. Press Return.
   The text field does not generate a text event. Instead, it generates an action event, and the action handler copies the text field's contents into the text area beneath it. The text area reacts by generating a single text event, no matter how many characters are copied into it.
4. Click the text area -- the large area at the bottom left of the applet -- and then press a character key on the keyboard.
   The text area fires a text event.

---

You can find the applet's code in TextEventDemo.java. This applet happens to implement its text event handling inside an inner class named MyTextListener. It creates and registers two instances of MyTextListener, one for each editable text component. The MyTextListener constructor takes a string describing the event source. When a MyTextListener instance detects a text event, (that is, MyTextListener's textValueChanged method is called), the instance adds a message to the display area at the right of the applet. Here is the applet's text event handling code:

public class TextEventDemo ... {
    TextField textField;
    TextArea textArea;
    TextArea displayArea;
    ...
        //where initialization occurs:
	textField = new TextField(20);
	...
	textField.addTextListener(new MyTextListener("Text Field"));

        textArea = new TextArea(5, 20);
	textArea.addTextListener(new MyTextListener("Text Area"));
	...
    }

    class MyTextListener implements TextListener {
	String preface;

	public MyTextListener(String source) {
	    preface = source
		      + " text value changed.\n"
		      + "   First 10 characters: \"";
	}

        public void textValueChanged(TextEvent e) {
	    TextComponent tc = (TextComponent)e.getSource();
	    String s = tc.getText();
	    ...//truncate s to 10 characters...

	    displayArea.append(preface + s + "\"\n");
	    ...
	}
    }
    ...
}

The TextEvent Class

Each text event method has a single parameter: a TextEvent object. The TextEvent class defines no generally useful methods. Using the getSource method that TextEvent inherits from EventObject, you can get the text component that generated the event and then send messages to it.

Using Components, the GUI Building Blocks