The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search

Trail: Creating a GUI with JFC/Swing
Lesson: Writing Event Listeners

How to Write a Caret Listener

Caret events occur when the caret in a text component moves or when the selection in a text component changes. You can attach a caret listener to an instance of any JTextComponent subclass with the addCaretListener method.

If your program has a custom caret, you might find it more convenient to attach a listener to the caret object rather than to the text component for which it is a caret. A caret fires change events rather than caret events, so you would need to write a change listener rather than a caret listener.

Here is the caret event handling code from an application called TextComponentDemo.

...
//where initialization occurs
CaretListenerLabel caretListenerLabel =
    new CaretListenerLabel("Caret Status");
...
textPane.addActionListener(caretListenerLabel);
...
protected class CaretListenerLabel extends JLabel
                                   implements CaretListener
{
    ...
    public void caretUpdate(CaretEvent e) {
        //Get the location in the text
        int dot = e.getDot();
        int mark = e.getMark();
	...
    }
}
You can find the full source code for the program and instructions for compiling and running it in General Rules for Using Text Components(in the Creating a GUI with JFC/Swing trail). For a discussion about the caret listener aspect of the program see Listening for Caret and Selection Changes(in the Creating a GUI with JFC/Swing trail).

The Caret Event API

The CaretListener interface has just one method, so it has no corresponding adapter class. Here's the method:
void caretUpdate(CaretEvent)
Called when the caret in the listened-to component moves or when the selection in the listened-to component changes.
The caretUpdate method has a single parameter: a CaretEvent(in the API reference documentation) object. To get the text component that fired the event, use the getSource method which CaretEvent inherits from EventObject(in the API reference documentation).

The CaretEvent class defines two useful methods:

int getDot()
Returns the current location of the caret. If text is selected, the caret marks one end of the selection.
int getMark()
Returns the other end of the selection. If nothing is selected, the value returned by this method is equal to the value returned by getDot. Note that the dot is not guaranteed to be less than the mark.

Examples that Use Caret Listeners

The following table lists the examples that use caret listeners.

Example Where Described Notes
TextComponentDemo Listening for Caret and Selection Changes(in the Creating a GUI with JFC/Swing trail) Uses a "listener label" to display caret and selection status.


Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search