Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.beans
Class DelayedPropertyChangeHandler

    java.lang.Object
      com.jgoodies.binding.beans.DelayedPropertyChangeHandler

All Implemented Interfaces:
  PropertyChangeListener, EventListener

    public abstract class DelayedPropertyChangeHandler

extends Object
implements PropertyChangeListener

A PropertyChangeListener that is intended to handle property changes after a specified delay. Useful to defer changes until a stable state is reached. For example if you look up a persistent object for a selection in a list. You don't want to find and transport objects that the user selects temporarily; you want to get only a stable selection. Or if you want to validate on every key typed, you may delay the validation until no key has been typed for a given time.

If this handler is notified about a property change it stores the PropertyChangeEvent it has received in `#propertyChange`, and starts a Swing Timer that will call `#delayedPropertyChange` after a delay. In coalescing mode a previously started timer - if any - will be stopped before. In other words, the timer is restarted.

TODO: Write about the recommended delay time - above the double-click time and somewhere below a second, e.g. 100ms to 200ms.

TODO: Summarize the differences between the DelayedReadValueModel, the DelayedWriteValueModel, and this DelayedPropertyChangeHandler.

Since:
  1.1
Version:
  $Revision: 1.19 $
Author:
  Karsten Lentzsch
See Also:
  `DelayedReadValueModel`, `DelayedWriteValueModel`, `Timer`

Field Summary
`static int` | `DEFAULT_DELAY` The delay in milliseconds used as default in the no-arg constructor.

Constructor Summary
`DelayedPropertyChangeHandler()` Constructs a DelayedPropertyChangeHandler with a default delay.
`DelayedPropertyChangeHandler(int delay)` Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the coalesce disabled.
`DelayedPropertyChangeHandler(int delay, boolean coalesce)` Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the given coalesce mode.

Method Summary
`abstract void` | `delayedPropertyChange(PropertyChangeEvent evt)` This method gets called after this handler's delay if a bound property has changed.
`int` | `getDelay()` Returns the delay, in milliseconds, that is used to defer value change notifications.
`boolean` | `isCoalesce()` Returns if this model coalesces all pending changes or not.
`boolean` | `isPending()` Checks and answers whether there are pending events.
`void` | `propertyChange(PropertyChangeEvent evt)` This handler has been notified about a change in a bound property.
`void` | `setCoalesce(boolean b)` Sets if this model shall coalesce all pending changes or not.
`void` | `setDelay(int delay)` Sets the delay, in milliseconds, that is used to defer value change notifications.
`void` | `stop()` Stops a running timer.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_DELAY

    public static final int DEFAULT_DELAY

  The delay in milliseconds used as default in the no-arg constructor.

  See Also:
    Constant Field Values

Constructor Detail

### DelayedPropertyChangeHandler

    public DelayedPropertyChangeHandler()

  Constructs a DelayedPropertyChangeHandler with a default delay.

### DelayedPropertyChangeHandler

    public DelayedPropertyChangeHandler(int delay)

  Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the coalesce disabled.

  Parameters:
    `delay` - the milliseconds to wait before the delayed property change will be performed
  Throws:
    `IllegalArgumentException` - if the delay is negative

### DelayedPropertyChangeHandler

    public DelayedPropertyChangeHandler(int delay,
                                        boolean coalesce)

  Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the given coalesce mode.

  Parameters:
    `delay` - the milliseconds to wait before the delayed property change will be performed
    `coalesce` - `true` to coalesce all pending changes, `false` to fire changes with the delay when an update has been received
  Throws:
    `IllegalArgumentException` - if the delay is negative
  See Also:
    `setCoalesce(boolean)`

Method Detail

### getDelay

    public final int getDelay()

  Returns the delay, in milliseconds, that is used to defer value change notifications.

  Returns:
    the delay, in milliseconds, that is used to defer value change notifications
  Since:
    1.5
  See Also:
    `setDelay(int)`

### setDelay

    public final void setDelay(int delay)

  Sets the delay, in milliseconds, that is used to defer value change notifications.

  Parameters:
    `delay` - the delay, in milliseconds, that is used to defer value change notifications
  Throws:
    `IllegalArgumentException` - if the delay is negative
  Since:
    1.5
  See Also:
    `getDelay()`

### isCoalesce

    public final boolean isCoalesce()

  Returns if this model coalesces all pending changes or not.

  Returns:
    `true` if all pending changes will be coalesced, `false` if pending changes are fired with a delay when an update has been received.
  See Also:
    `setCoalesce(boolean)`

### setCoalesce

    public final void setCoalesce(boolean b)

  Sets if this model shall coalesce all pending changes or not. In this case, a change event will be fired first, if no updates have been received for this model's delay. If coalesce is `false`, a change event will be fired with this model's delay when an update has been received.

  The default value is `false`.

  Note that this value is not the #coalesce value of this model's internal Swing timer.

  Parameters:
    `b` - `true` to coalesce, `false` to fire separate changes

### stop

    public final void stop()

  Stops a running timer. Pending events - if any - are canceled and won't be delivered to `#delayedPropertyChange`.

  Since:
    1.2

### isPending

    public final boolean isPending()

  Checks and answers whether there are pending events.

  Returns:
    `true` if there are pending events, `false` if not.
  Since:
    2.0.4

### propertyChange

    public final void propertyChange(PropertyChangeEvent evt)

  This handler has been notified about a change in a bound property. Stores the given event, then starts a timer that'll call `#delayedPropertyChange` after this handler's delay. If coalescing is enabled, a previously started timer - if any - if stopped before. In other words, the timer is restarted.

  Specified by:
    `propertyChange` in interface `PropertyChangeListener`
  Parameters:
    `evt` - the PropertyChangeEvent describing the event source and the property that has changed

### delayedPropertyChange

    public abstract void delayedPropertyChange(PropertyChangeEvent evt)

  This method gets called after this handler's delay if a bound property has changed. The event is the pending event as stored in `#propertyChange`.

  Parameters:
    `evt` - the PropertyChangeEvent describing the event source and the property that has changed

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2013 JGoodies Software GmbH. All Rights Reserved.