de.sciss.app
Class DynamicPrefChangeManager

java.lang.Object
  de.sciss.app.DynamicPrefChangeManager

All Implemented Interfaces:

DynamicListening, LaterInvocationManager.Listener, PreferenceNodeSync, java.util.EventListener, java.util.prefs.PreferenceChangeListener

public class DynamicPrefChangeManager
extends java.lang.Object
implements DynamicListening, java.util.prefs.PreferenceChangeListener, PreferenceNodeSync, LaterInvocationManager.Listener

A utility class for a mechanism common to many GUI objects : they listen to certain preferences and need to act upon changes. However to improve performance, the listening is paused when the components are hidden and resumed when they are shown or added to ancestor GUI components.

This class tracks a set of preferences specified by key strings. It implements the DynamicListening interface and thus can be used in a DynamicAncestorAdapter. When the listening is resumes, this class checks for changes that might have occured to the tracked preferences. All relevant PreferenceChangeEvents are forwarded to the LaterInvocationManager.Listener provided in the constructor call.

Another important issue is to avoid deadlocks that can be easily caused in the java.util.prefs.Preferences context because it provides no means to find out who changed the preferences. Therefore if a component both changes a preferences and tracks (listens to) changes of the same preference, it can produce and infinite loop. Besides, if another component changes to prefs but the old value equals the new value, unneccessary overhead might be created. To avoid this, this class checks to see if a preference value really changed - if not, that PreferenceChangeEvent is NOT forwarded to the LIM-Listener.

Version:

0.14, 20-Mar-08

Author:

Hanns Holger Rutz

Constructor Summary

DynamicPrefChangeManager(java.util.prefs.Preferences prefs, java.lang.String[] keys, java.util.prefs.PreferenceChangeListener client)

DynamicPrefChangeManager(java.util.prefs.Preferences prefs, java.lang.String[] keys, java.util.prefs.PreferenceChangeListener client, boolean initialDelivery)
Constructs a new DynamicPrefChangeManager.

Method Summary

void	deliverChanges()
void	laterInvocation(java.lang.Object o) Called later in the event thread, this passes the object given to the queue method
void	preferenceChange(java.util.prefs.PreferenceChangeEvent e)
void	setPreferences(java.util.prefs.Preferences prefs) Enables Preferences synchronization.
void	startListening() will be called when the component becomes visible
void	stopListening() will be called when the component is hidden

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynamicPrefChangeManager

public DynamicPrefChangeManager(java.util.prefs.Preferences prefs,
                                java.lang.String[] keys,
                                java.util.prefs.PreferenceChangeListener client)

DynamicPrefChangeManager

public DynamicPrefChangeManager(java.util.prefs.Preferences prefs,
                                java.lang.String[] keys,
                                java.util.prefs.PreferenceChangeListener client,
                                boolean initialDelivery)

Constructs a new DynamicPrefChangeManager.

Parameters:

prefs - the Preference object to track. Note that the constructor does not register a PreferenceChangeListener, this is done when the DynamicListening.startListening() is involved. Therefore if you plan to not attach the DynamicPrefChangeManager to a DynamicAncestor- or -ComponentListener, you'll have to call startListening() manually.

keys - the keys in the specified prefs which we shall track. Initially all values are considered null and nothing is broadcast. However, if startListening() is called, all values are checked, therefore all preference values which are not null will be initially forwarded to the LIM-Listener.

client - usually the calling instance. laterInvocation() is called whenever the dynamic listening is active and preference changes occur which really alter the preference values. The object passed to laterInvocation is a PreferenceChangeEvent.

Method Detail

setPreferences

public void setPreferences(java.util.prefs.Preferences prefs)

Description copied from interface: PreferenceNodeSync

Enables Preferences synchronization. This method is not thread safe and must be called from the event thread. When a preference change is received, the GUI is updated and dispatches an event to registered listeners. Likewise, if the user adjusts the GUI value, the preference will be updated. The same is true, if you call one of the value changing methods.

Specified by:

setPreferences in interface PreferenceNodeSync

Parameters:

prefs - the preferences node in which the values are stored, or null to disable prefs sync.

deliverChanges

public void deliverChanges()

startListening

public void startListening()

Description copied from interface: DynamicListening

will be called when the component becomes visible

Specified by:

startListening in interface DynamicListening

stopListening

public void stopListening()

Description copied from interface: DynamicListening

will be called when the component is hidden

Specified by:

stopListening in interface DynamicListening

laterInvocation

public void laterInvocation(java.lang.Object o)

Description copied from interface: LaterInvocationManager.Listener

Called later in the event thread, this passes the object given to the queue method

Specified by:

laterInvocation in interface LaterInvocationManager.Listener

Parameters:

o - object as passed to queue

preferenceChange

public void preferenceChange(java.util.prefs.PreferenceChangeEvent e)

Specified by:

preferenceChange in interface java.util.prefs.PreferenceChangeListener