The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

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. 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.

### 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 | Uses a "listener label" to display caret and selection status.

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form