How to Write a Property-Change Listener

< Day Day Up >

Property-change events occur whenever the value of a bound property changes for a bean ”a component that conforms to the JavaBeans ^TM specification. ^[32] All Swing components are also beans.

^[32] You can find out more about beans from the "JavaBeans" trail of The Java Tutorial . This trail is available online and is included on the CD at JavaTutorial/beans/index.html .

A JavaBeans property is accessed through its get and set methods . JComponent , for example, has the property font which is accessible through the 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.

Some scenarios that commonly require property-change listeners include:

You have implemented a formatted text field and need a way to detect when the user has entered a new value. You can register a property-change listener on the formatted text field to listen to changes on the value property. See FormattedTextFieldDemo in How to Use Formatted Text Fields (page 221) for an example of this.
You have implemented a dialog and need to know when a user has clicked one of the dialog's buttons or changed a selection in the dialog. See DialogDemo in How to Make Dialogs (page 187) for an example of registering a property-change listener on an option pane to listen to changes to the value property. You can also check out FileChooserDemo2 in How to Use File Choosers (page 206) for an example of how to register a property-change listener to listen to changes to the directoryChanged and selectedFileChanged properties.
You need to be notified when the component that has the focus changes. You can register a property-change listener on the keyboard focus manager to listen to changes to the focusOwner property. See TrackFocusDemo and DragPictureDemo in How to Use the Focus Subsystem (page 583) for examples of this.

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 addPropertyChangeListener(PropertyChangeListener) method. 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, 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 addPropertyChange- Listener :

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

Table 30 lists the methods for registering a PropertyChangeListener and Table 31 lists the methods in the PropertyChangeListener interface. Table 32 describes the methods in the PropertyChangeEvent class. Note that because PropertyChangeListener has only one method, it has no corresponding adapter class. Also refer to the PropertyChangeListener API documentation at: http://java.sun.com/j2se/1.4.2/docs/api/java/beans/PropertyChangeListener.html. The PropertyChangeEvent API documentation is at: http://java.sun.com/j2se/1.4.2/docs/api/java/beans/PropertyChangeEvent.html.

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

Table 31. The PropertyChangeListener Interface

Method	Purpose
`propertyChange(PropertyChangeEvent)`	Called when the listened-to bean changes a bound property.

Table 32. 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 examples use property-change listeners.

Example	Where Described	Notes
`FormattedTextFieldDemo`	How to Use Formatted Text Fields (page 221)	A property-change listener is registered on several formatted text fields to track changes to the value property.
`DialogDemo`	How to Make Dialogs (page 187)	The `CustomDialog` class registers a property-change listener on an option pane to listen to the value and inputValue properties.
`FileChooserDemo2`	How to Use File Choosers (page 206)	The `ImagePreview` 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 (page 583)	A property-change listener is registered on the keyboard focus manager to track changes to the focusOwner property.

< Day Day Up >