bibliothek.gui.dock.support.mode
Class ModeManager<H,M extends Mode<H>>

java.lang.Object
  bibliothek.gui.dock.support.mode.ModeManager<H,M>

Type Parameters:

H - the kind of properties that are to be stored in this manager

M - the kind of Modes used by this manager

Direct Known Subclasses:

LocationModeManager

public abstract class ModeManager<H,M extends Mode<H>>
extends Object

Associates Dockables with one Mode out of a set of modes. This manager remembers in which order the modes were applied to a Dockable.

Author:

Benjamin Sigg

Constructor Summary

ModeManager(DockController controller)
Creates a new manager.

Method Summary

void	add(String key, Dockable dockable) Registers a new Dockable at this manager.
void	addAffected(Iterable<Dockable> dockables) Adds all elements of dockables to the current AffectedSet.
void	addEmpty(String key) Adds an empty entry to this manager.
void	addModeManagerListener(ModeManagerListener<? super H,? super M> listener) Adds a listener to this manager, the listener will be informed about changes in this manager.
void	addToModeHistory(Dockable dockable, M mode, H history) Adds the history data history to dockable for mode mode, and stores mode as the newest used mode.
void	apply(Dockable dockable, M mode, AffectedSet set, boolean force) Alters the mode of dockable to mode.
void	apply(Dockable dockable, M mode, boolean force) Alters the mode of dockable to mode.
void	apply(Dockable dockable, M mode, H history, AffectedSet set) Alters the mode of dockable to be mode.
boolean	apply(Dockable dockable, Path mode, AffectedSet set, boolean force) Alters the mode of dockable to mode.
boolean	apply(Dockable dockable, Path mode, boolean force) Alters the mode of dockable to mode.
boolean	apply(Dockable dockable, Path mode, H history, AffectedSet set) Alters the mode of dockable to be mode.
protected abstract void	applyDuringRead(String key, Path old, Path current, Dockable dockable) Called while reading modes in readSettings(ModeSettings).
protected boolean	createEntryDuringRead(String key) Tells whether an entry for a missing Dockable should be created.
<B> ModeSettings<H,B>	createModeSettings(ModeSettingsConverter<H,B> converter) Creates the empty set of settings for this ModeManager.
<B> ModeSettings<H,B>	createSettings(ModeSettingsConverter<H,B> converter) Creates a new ModeSetting which is configured to transfer data from this ModeManager to persistent storage or the other way.
void	destroy() Unregisters listeners which this manager added to the DockController and other components.
protected void	fireAdded(Dockable dockable) Calls ModeManagerListener.dockableAdded(ModeManager, Dockable) on all listeners that are currently registered
protected void	fireAdded(M mode) Calls ModeManagerListener.modeAdded(ModeManager, Mode) on all listeners that are currently registered.
protected void	fireModeChanged(Dockable dockable, M oldMode, M newMode) Calls ModeManagerListener.modeChanged(ModeManager, Dockable, Mode, Mode) on all listeners that are currently registered.
protected void	fireRemoved(Dockable dockable) Calls ModeManagerListener.dockableRemoved(ModeManager, Dockable) on all listeners that are currently registered.
protected void	fireRemoved(M mode) Calls ModeManagerListener.modeRemoved(ModeManager, Mode) on all listeners that are currently registered.
DockController	getController() Gets the controller in whose realm this manager works.
M	getCurrentMode(Dockable dockable) Tries to find the mode dockable is currently in.
protected M	getDefaultMode(Dockable dockable) Gets the default mode of dockable, the mode dockable is in if nothing else is specified.
Dockable	getDoubleClickTarget(Dockable target) Given some Dockable on which an event was registered, searches a registered dockable that is a child of target or target itself.
Collection<ModeSettingFactory<H>>	getFactories() Gets a set containing all the ModeSettingFactorys that were added to this manager.
H	getHistory(Dockable dockable, Path modeId) Gets the history of dockable in mode modeId.
HistoryRewriter<H,M>	getHistoryRewriter() Gets the current HistoryRewriter.
String	getKey(Dockable dockable) Gets the unique identifier which is used for dockable.
M	getMode(Path path) Searches and returns the mode with given unique identifier path.
List<M>	getModeHistory(Dockable dockable) Gets the history which modes dockable used in the past.
M	getPreviousMode(Dockable dockable) Reading the history this method tells which mode dockable was in before the current mode.
protected H	getProperties(M mode, Dockable dockable) Gets the properties which correspond to dockable and mode.
List<H>	getPropertyHistory(Dockable dockable) Gets the history which properties dockable used in the past.
abstract DockActionSource	getSharedActions(DockStation station) Gets a list of actions that should be shown on station depending on the current children of station.
boolean	isEmpty(String key) Tells whether information about dockable key gets stored indefinitely or not.
boolean	isOnContinuous() Tells whether this manager currently runs a continuous transaction.
boolean	isOnTransaction() Tells whether this manager is currently changing the Mode of a Dockable.
boolean	isRegistered(Dockable dockable) Tells whether this ModeManager knows dockable and can handle a call to any of the apply methods.
Set<Dockable>	listDockables() Returns a set containing all Dockables that are currently registered at this manager.
protected ModeManagerListener<? super H,? super M>[]	listeners() Gets all the listeners that are currently registered in this manager.
Iterable<M>	modes() Returns an iteration of all modes that are stored in this manager.
void	put(String key, Dockable dockable) Registers a new Dockable at this manager.
void	putFactory(ModeSettingFactory<H> factory) Adds a factory to this ModeManager.
void	putMode(M mode) Puts a new mode in this manager.
void	readSettings(ModeSettings<H,?> settings) Reads the contents of settings and stores it.
Runnable	readSettings(ModeSettings<H,?> settings, UndoableModeSettings pending) Reads the contents of settings, creates new entries if either createEntryDuringRead(String) or if pending allows the setting to be undone if not needed.
protected void	rebuild(Dockable dockable) Rebuilds the action sources of dockable.
protected void	rebuildAll() Rebuilds the actions sources for all Dockables.
void	reduceToEmpty(Dockable dockable) Removes dockable itself, put the properties of dockable remain in the system.
void	refresh() Updates the modes of all Dockables that are registered at this ModeManager.
void	refresh(Dockable dockable, boolean recursive) Updates the mode of dockable and updates the actions associated with dockable.
void	remove(Dockable dockable) Removes the properties that belong to dockable.
void	removeEmpty(String name) Removes the entry for name but only if the entry is not associated with any Dockable.
void	removeMode(M mode) Removes mode from this manager.
void	removeModeManagerListener(ModeManagerListener<? super H,? super M> listener) Removes listener from this manager.
void	runTransaction(AffectingRunnable runnable) Runs an algorithm which affects the mode of some Dockables.
void	runTransaction(AffectingRunnable run, boolean continuous) Runs an algorithm which affects the mode of some Dockables.
void	runTransaction(Runnable run) Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
void	runTransaction(Runnable run, boolean continuous) Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
void	setHistoryRewriter(HistoryRewriter<H,M> historyRewriter) Sets the current HistoryRewriter.
protected void	setProperties(M mode, Dockable dockable, H property) Stores a property for dockable if in mode mode.
void	store(Dockable dockable) Stores the current location of dockable and all its children in respect to their current Mode.
protected void	store(M mode, Dockable dockable) Stores the location of dockable under the key mode. This method does nothing if isOnContinuous() returns true
String	toString()
void	writeSettings(ModeSettings<H,?> setting) Writes all the information stored in this ModeManager to setting.

Methods inherited from class java.lang.Object

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

Constructor Detail

ModeManager

public ModeManager(DockController controller)

Creates a new manager.

Parameters:

controller - the controller in whose realm this manager will work

Method Detail

destroy

public void destroy()

Unregisters listeners which this manager added to the DockController and other components.

getController

public DockController getController()

Gets the controller in whose realm this manager works.

Returns:

the controller

addModeManagerListener

public void addModeManagerListener(ModeManagerListener<? super H,? super M> listener)

Adds a listener to this manager, the listener will be informed about changes in this manager.

Parameters:

listener - the new listener, not null

removeModeManagerListener

public void removeModeManagerListener(ModeManagerListener<? super H,? super M> listener)

Removes listener from this manager.

Parameters:

listener - the listener to remove

putMode

public void putMode(M mode)

Puts a new mode in this manager. If there is already a mode with the same id registered, then the old mode gets replaced by the new one.

Parameters:

mode - the new mode

putFactory

public void putFactory(ModeSettingFactory<H> factory)

Adds a factory to this ModeManager. The factory will be used by the ModeSettings to read and write data of the mode with the same identifier as factory persistently.
Note: A Mode might also provide a ModeSettingFactory, if there is a collision of unique identifiers the factory of the mode is used.

Parameters:

factory - the new factory

getFactories

public Collection<ModeSettingFactory<H>> getFactories()

Gets a set containing all the ModeSettingFactorys that were added to this manager.

Returns:

the factories

removeMode

public void removeMode(M mode)

Removes mode from this manager. Note that history information about the mode remains.

Parameters:

mode - the mode to remove

getMode

public M getMode(Path path)

Searches and returns the mode with given unique identifier path.

Parameters:

path - some unique identifier

Returns:

the mode with that identifier or null

setHistoryRewriter

public void setHistoryRewriter(HistoryRewriter<H,M> historyRewriter)

Sets the current HistoryRewriter. The rewriter is invoked every time before the apply method of a Mode is called. The rewriter can then change the history of one Dockable, e.g. to apply additional checks whether an old state is still valid.
A history rewriter does not change the history permanently. It creates a new history object before the apply method is called, but that new history object will not be stored by the ModeManager.

Parameters:

historyRewriter - the new rewriter, can be null

getHistoryRewriter

public HistoryRewriter<H,M> getHistoryRewriter()

Gets the current HistoryRewriter.

Returns:

the rewriter, can be null

See Also:

setHistoryRewriter(HistoryRewriter)

listeners

protected ModeManagerListener<? super H,? super M>[] listeners()

Gets all the listeners that are currently registered in this manager.

Returns:

the list of registered listeners

fireAdded

protected void fireAdded(Dockable dockable)

Calls ModeManagerListener.dockableAdded(ModeManager, Dockable) on all listeners that are currently registered

Parameters:

dockable - the new element

fireRemoved

protected void fireRemoved(Dockable dockable)

Calls ModeManagerListener.dockableRemoved(ModeManager, Dockable) on all listeners that are currently registered.

Parameters:

dockable - the removed element

fireModeChanged

protected void fireModeChanged(Dockable dockable,
                               M oldMode,
                               M newMode)

Calls ModeManagerListener.modeChanged(ModeManager, Dockable, Mode, Mode) on all listeners that are currently registered.

Parameters:

dockable - the element whose mode changed

oldMode - its old mode

newMode - its new mode

fireAdded

protected void fireAdded(M mode)

Calls ModeManagerListener.modeAdded(ModeManager, Mode) on all listeners that are currently registered.

Parameters:

mode - the added mode

fireRemoved

protected void fireRemoved(M mode)

Calls ModeManagerListener.modeRemoved(ModeManager, Mode) on all listeners that are currently registered.

Parameters:

mode - the removed mode

add

public void add(String key,
                Dockable dockable)

Registers a new Dockable at this manager. If there is already mode-information for key present, then dockable inherits this information.

Parameters:

key - the unique key of dockable

dockable - the new element

Throws:

NullPointerException - if either key or dockable is null

IllegalArgumentException - if there is already a dockable registered with key

put

public void put(String key,
                Dockable dockable)

Registers a new Dockable at this manager. This method works like add(String, Dockable) but does not throw an exception if another Dockable is already registered with key. Instead the other Dockable is unregistered and docakble inherits its mode-information.

Parameters:

key - the unique identifier of dockable

dockable - some new element

Throws:

NullPointerException - if either key or dockable is null

getKey

public String getKey(Dockable dockable)

Gets the unique identifier which is used for dockable.

Parameters:

dockable - some element

Returns:

the unique identifier or null if dockable is not registered

isRegistered

public boolean isRegistered(Dockable dockable)

Tells whether this ModeManager knows dockable and can handle a call to any of the apply methods.

Parameters:

dockable - the element to check

Returns:

true if the element is known, false otherwise

listDockables

public Set<Dockable> listDockables()

Returns a set containing all Dockables that are currently registered at this manager.

Returns:

the set of dockables

runTransaction

public void runTransaction(AffectingRunnable runnable)

Runs an algorithm which affects the mode of some Dockables.

Parameters:

runnable - the algorithm, null will be ignored

runTransaction

public void runTransaction(AffectingRunnable run,
                           boolean continuous)

Runs an algorithm which affects the mode of some Dockables.

Parameters:

run - the algorithm, null will be ignored

continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

runTransaction

public void runTransaction(Runnable run)

Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.

Parameters:

run - the runnable to execute

runTransaction

public void runTransaction(Runnable run,
                           boolean continuous)

Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.

Parameters:

run - the runnable to execute

continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     boolean force)

Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, boolean).

Parameters:

dockable - the element whose mode is going to be changed

mode - the new mode

force - if true dockable is relocated even if the current mode already is mode

Returns:

true if mode was found, false otherwise

Throws:

IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

apply

public void apply(Dockable dockable,
                  M mode,
                  boolean force)

Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).

Parameters:

dockable - the element whose mode is going to be changed

mode - the new mode

force - if true dockable is relocated even if the current mode already is mode

Throws:

IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     AffectedSet set,
                     boolean force)

Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).

Parameters:

dockable - the element whose mode is going to be changed

mode - the new mode

set - to store all dockables whose mode might have been changed

force - if true dockable is relocated even if the current mode already is mode

Returns:

true if mode was found, false otherwise

Throws:

IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

apply

public void apply(Dockable dockable,
                  M mode,
                  AffectedSet set,
                  boolean force)

Alters the mode of dockable to mode. This method does nothing if the current mode of dockable already is mode.
After initial checks and reading the history, this method calls apply(Dockable, Mode, Object, AffectedSet).

Parameters:

dockable - the element whose mode is going to be changed

mode - the new mode

set - to store all dockables whose mode might have been changed

force - if true dockable is relocated even if the current mode already is mode

Throws:

IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

getHistory

public H getHistory(Dockable dockable,
                    Path modeId)

Gets the history of dockable in mode modeId.

Parameters:

dockable - the element whose history is searched

modeId - the identifier of the mode

Returns:

the history information or null if not found

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     H history,
                     AffectedSet set)

Alters the mode of dockable to be mode. This method just calls apply(Dockable, Mode, Object, AffectedSet).

Parameters:

dockable - the element whose mode is changed

mode - the new mode of dockable

history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null

set - to store elements that have changed

Returns:

true if mode was found, false otherwise

Throws:

IllegalArgumentException - if either dockable, mode or set is null

apply

public void apply(Dockable dockable,
                  M mode,
                  H history,
                  AffectedSet set)

Alters the mode of dockable to be mode. This method does not alter the modes of other dockables, notice however that the methods Mode.apply(Dockable, Object, AffectedSet) may trigger additional mode-changes.

Parameters:

dockable - the element whose mode is changed

mode - the new mode of dockable

history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null

set - to store elements that have changed

Throws:

IllegalArgumentException - if either dockable, mode or set is null

setProperties

protected void setProperties(M mode,
                             Dockable dockable,
                             H property)

Stores a property for dockable if in mode mode. This method does not trigger any version of the apply methods.

Parameters:

mode - the mode which is affected

dockable - the dockables whose property is changed

property - the new property, can be null

getProperties

protected H getProperties(M mode,
                          Dockable dockable)

Gets the properties which correspond to dockable and mode.

Parameters:

mode - the first part of the key

dockable - the second part of the key

Returns:

the properties or null

isOnTransaction

public boolean isOnTransaction()

Tells whether this manager is currently changing the Mode of a Dockable.

Returns:

true if a mode is currently working

isOnContinuous

public boolean isOnContinuous()

Tells whether this manager currently runs a continuous transaction. As long as a continuous transaction is running the internal states of this manager do not change.

Returns:

whether a continuous transaction is running

refresh

public void refresh()

Updates the modes of all Dockables that are registered at this ModeManager.

refresh

public void refresh(Dockable dockable,
                    boolean recursive)

Updates the mode of dockable and updates the actions associated with dockable. This method is intended to be called by any code that changes the mode in a way that is not automatically registered by this ModeManager.

Parameters:

dockable - the element whose mode might have changed

recursive - if set, then the children of dockable are refreshed as well.

remove

public void remove(Dockable dockable)

Removes the properties that belong to dockable.

Parameters:

dockable - the element to remove

reduceToEmpty

public void reduceToEmpty(Dockable dockable)

Removes dockable itself, put the properties of dockable remain in the system.

Parameters:

dockable - the element to reduce

applyDuringRead

protected abstract void applyDuringRead(String key,
                                        Path old,
                                        Path current,
                                        Dockable dockable)

Called while reading modes in readSettings(ModeSettings). Subclasses might change the mode according to newMode.

Parameters:

key - the identifier of dockable

old - the mode dockable is currently in

current - the mode dockable is going to be

dockable - the element that changes its mode, might be null

createEntryDuringRead

protected boolean createEntryDuringRead(String key)

Tells whether an entry for a missing Dockable should be created. This will result in a call to addEmpty(String) during readSettings(ModeSettings). The default implementation returns always false.

Parameters:

key - the key for which to create a new entry

Returns:

true if an entry should be created

addEmpty

public void addEmpty(String key)

Adds an empty entry to this manager. The empty entry can be used to store information for a Dockable that has not yet been created. It is helpful if the client intends to load first its properties and create only those Dockables which are visible.
Also an empty entry gets never deleted unless removeEmpty(String) is called.

Parameters:

key - the name of the empty entry

Throws:

NullPointerException - if key is null

removeEmpty

public void removeEmpty(String name)

Removes the entry for name but only if the entry is not associated with any Dockable.

Parameters:

name - the name of the entry which might be empty

Throws:

NullPointerException - if key is null

isEmpty

public boolean isEmpty(String key)

Tells whether information about dockable key gets stored indefinitely or not.

Parameters:

key - the key to check

Returns:

true if the key is never removed automatically false otherwise

getDoubleClickTarget

public Dockable getDoubleClickTarget(Dockable target)

Given some Dockable on which an event was registered, searches a registered dockable that is a child of target or target itself.

Parameters:

target - the target whose registered child is searched

Returns:

target, a child of target, or null

getDefaultMode

protected M getDefaultMode(Dockable dockable)

Gets the default mode of dockable, the mode dockable is in if nothing else is specified. This method checks Mode.isDefaultMode(Dockable) and returns the first Mode where the answer was true.

Parameters:

dockable - some dockable, not null

Returns:

its default mode, must be registered at this ModeManager and not be null

getCurrentMode

public M getCurrentMode(Dockable dockable)

Tries to find the mode dockable is currently in. This method calls Mode.isCurrentMode(Dockable) and returns the first Mode where the answer was true.

Parameters:

dockable - some dockable, not null

Returns:

the current mode or null if not found

getPreviousMode

public M getPreviousMode(Dockable dockable)

Reading the history this method tells which mode dockable was in before the current mode.

Parameters:

dockable - some element

Returns:

the previous mode or null if this information is not available

getModeHistory

public List<M> getModeHistory(Dockable dockable)

Gets the history which modes dockable used in the past. The older entries are at the beginning of the list. The current mode may or may not be included in the list.

Parameters:

dockable - the element whose history is asked

Returns:

the history or an empty list if no history is available

addToModeHistory

public void addToModeHistory(Dockable dockable,
                             M mode,
                             H history)

Adds the history data history to dockable for mode mode, and stores mode as the newest used mode.

Parameters:

dockable - the element whose history is modified must be known to this manager

mode - the mode whose history is modified

history - the new history

Throws:

IllegalStateException - if dockable is not known to this manager

getPropertyHistory

public List<H> getPropertyHistory(Dockable dockable)

Gets the history which properties dockable used in the past. Entries of value null are ignored. The older entries are at the beginning of the list.

Parameters:

dockable - the element whose history is asked

Returns:

the history or an empty list if no history is available

store

public void store(Dockable dockable)

Stores the current location of dockable and all its children in respect to their current Mode. Dockables that are not registered at this manager are ignored.
This method does nothing if isOnContinuous() returns true

Parameters:

dockable - a root of a tree

store

protected void store(M mode,
                     Dockable dockable)

Stores the location of dockable under the key mode.
This method does nothing if isOnContinuous() returns true

Parameters:

mode - the mode dockable is currently in

dockable - the element whose location will be stored

modes

public Iterable<M> modes()

Returns an iteration of all modes that are stored in this manager.

Returns:

the iteration

rebuildAll

protected void rebuildAll()

Rebuilds the actions sources for all Dockables.

rebuild

protected void rebuild(Dockable dockable)

Rebuilds the action sources of dockable.

Parameters:

dockable - the element whose actions are to be updated

getSharedActions

public abstract DockActionSource getSharedActions(DockStation station)

Gets a list of actions that should be shown on station depending on the current children of station. This method is called everytime when either a child is added, removed or selected on station.

Parameters:

station - the station whose actions are asked

Returns:

the actions, can be null

createSettings

public <B> ModeSettings<H,B> createSettings(ModeSettingsConverter<H,B> converter)

Creates a new ModeSetting which is configured to transfer data from this ModeManager to persistent storage or the other way. The new setting contains all the ModeSettingFactorys which are currently known to this manager.

Type Parameters:

B - the intermediate format

Parameters:

converter - conversion tool from this managers meta-data format to the intermediate format.

Returns:

the new empty settings

createModeSettings

public <B> ModeSettings<H,B> createModeSettings(ModeSettingsConverter<H,B> converter)

Creates the empty set of settings for this ModeManager. Subclasses may override this method to use another set of settings. This method does not need to call ModeSettings.addFactory(ModeSettingFactory).

Type Parameters:

B - the intermediate format

Parameters:

converter - converstion tool from this managers meta-data format to the intermediate format.

Returns:

the new empty settings

writeSettings

public void writeSettings(ModeSettings<H,?> setting)

Writes all the information stored in this ModeManager to setting.

Parameters:

setting - the settings to fill

readSettings

public void readSettings(ModeSettings<H,?> settings)

Reads the contents of settings and stores it.

Parameters:

settings - the settings to read

readSettings

public Runnable readSettings(ModeSettings<H,?> settings,
                             UndoableModeSettings pending)

Reads the contents of settings, creates new entries if either createEntryDuringRead(String) or if pending allows the setting to be undone if not needed.

Parameters:

settings - the settings to read

pending - undoable settings, can be null

Returns:

an algorithm that will remove any entry that was created because pending did advise so, null if pending was null

addAffected

public void addAffected(Iterable<Dockable> dockables)

Adds all elements of dockables to the current AffectedSet.

Parameters:

dockables - the elements to add

toString

public String toString()

Overrides:

toString in class Object