The JavaTM Tutorial
Previous Page Lesson Contents Next Page 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 Property Change Listener

Property-change events occur whenever the value of a bound property changes for a bean — a component that conforms to the JavaBeansTM specification. You can find out more about beans from the JavaBeans (in the Creating a GUI with JFC/Swing trail) trail of the Java Tutorial (in the Creating a GUI with JFC/Swing trail). All Swing components are also beans.

A JavaBeans property is accessed through its get and set methods. For example, JComponent has the property font which is accessible through getFont and setFont methods.

A bound property fulfills the special requirement that, besides the get and set methods, it fires a property-change event when its value changes. If you are interested in more information, see the Bound Properties (in the Creating a GUI with JFC/Swing trail) page in the JavaBeans trail.

Some scenarios that commonly require property-change listeners include:

Although these are some of the more common uses for property-change listeners, you can register a property-change listener on the bound property of any component that conforms to the JavaBeans specification.

You can register a property change listener in two ways. The first uses the method addPropertyChangeListener(PropertyChangeListener). When you register a listener this way, you are notified of every change to every bound property for that object. In the propertyChange method, you can get the name of the property that has changed using the PropertyChangeEvent getPropertyName method, as in the following code snippet:

KeyboardFocusManager focusManager =
   KeyboardFocusManager.getCurrentKeyboardFocusManager();
focusManager.addPropertyChangeListener(new FocusManagerListener());
...
public FocusManagerListener() implements PropertyChangeListener {
    public void propertyChange(PropertyChangeEvent e) {
        String propertyName = e.getPropertyName();
        if ("focusOwner".equals(propertyName) {
            ...
        } else if ("focusedWindow".equals(propertyName) {
            ...
        }
    }
    ...
}

The second way to register a property change listener uses the method addPropertyChangeListener(String, PropertyChangeListener). The String argument is the name of a property. Using this method means that you only receive notification when a change occurs to that particular property. So, for example, if you registered a property change listener like this:

aComponent.addPropertyChangeListener("font",
                                     new FontListener());

FontListener only receives notification when the value of the component's font property changes. It does not receive notification when the value changes for transferHandler, opaque, border, or any other property.

The following example shows how to register a property change listener on the value property of a formatted text field using the two-argument version of addPropertyChangeListener:

//...where initialization occurs:
double amount;
JFormattedTextField amountField;
...
amountField.addPropertyChangeListener("value",
                                      new FormattedTextFieldListener());
...
class FormattedTextFieldListener implements PropertyChangeListener {
    public void propertyChanged(PropertyChangeEvent e) {
        Object source = e.getSource();
        if (source == amountField) {
            amount = ((Number)amountField.getValue()).doubleValue();
            ...
        }
        ...//re-compute payment and update field...
    }
}

The Property Change Listener API

Registering a PropertyChangeListener

Method Purpose
addPropertyChangeListener(PropertyChangeListener) Add a property-change listener to the listener list.
addPropertyChangeListener(String, PropertyChangeListener) Add a property-change listener for a specific property. The listener is called only when there is a change to the specified property.

The PropertyChangeListener Interface

Because PropertyChangeListener has only one method, it has no corresponding adapter class.
Method Purpose
propertyChange(PropertyChangeEvent) Called when the listened-to bean changes a bound property.

The PropertyChangeEvent Class

Method Purpose
Object getNewValue()
Object getOldValue()
Return the new, or old, value of the property, respectively.
String getPropertyName() Return the name of the property that was changed.

Examples that Use Property Change Listeners

The following table lists the examples that use property-change listeners.

Example Where Described Notes
FormattedTextFieldDemo How to Use Formatted Text Fields (in the Creating a GUI with JFC/Swing trail) A property-change listener is registered on several formatted text fields to track changes to the value property.
DialogDemo How to Make Dialogs (in the Creating a GUI with JFC/Swing trail) The CustomDialog (in the Creating a GUI with JFC/Swing trail) class registers a property-change listener on an option pane to listen to the value and inputValue properties.
FileChooserDemo2 How to Use File Choosers (in the Creating a GUI with JFC/Swing trail) The ImagePreview (in the Creating a GUI with JFC/Swing trail) class registers a property-change listener on the file chooser to listen to the directoryChanged and selectedFileChanged properties.
TrackFocusDemo How to Use the Focus Subsystem (in the Creating a GUI with JFC/Swing trail) A property-change listener is registered on the keyboard focus manager to track changes to the focusOwner property.


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

Copyright 1995-2005 Sun Microsystems, Inc. All rights reserved.