Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

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. For a discussion about the caret listener aspect of the program see Listening for Caret and Selection Changes.

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 object. To get the text component that fired the event, use the getSource method which CaretEvent inherits from EventObject.

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.

The following table lists the examples that use caret listeners.

Example	Where Described	Notes
TextComponentDemo	Listening for Caret and Selection Changes	Uses a "listener label" to display caret and selection status.

Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form