bibliothek.gui
Class DockFrontend

java.lang.Object
  extended by bibliothek.gui.DockFrontend
Direct Known Subclasses:
CDockFrontend

public class DockFrontend
extends Object

A DockFrontend provides some methods to handle the storage of various layouts. The frontend can save the current layout (the location of all Dockables) and later restore it. Each set of properties is stored in a Setting. Subclasses might override the following methods to store additional information:


The frontend has a list of Dockables. It assumes that these Dockables never change. The frontend can add a "close"-button to these Dockables. The location of these Dockables is stored as well. Dockables which are not added to this frontend, are just ignored.
Note: Clients must provide a set of root stations (addRoot). The frontend will only store the locations of children of these roots. The frontend adds these roots also to its controller, but the frontend does not observe the controller, and so all changes must be applied directly on the frontend (on the other hand, clients may use more than one frontend).
Clients must also provide some factories to allow the storage of their elements. The default-factories are already installed.
Note: Clients may use the Common project instead of DockFrontend. The Common project offers way more features than DockFrontend and is even easier to handle.

Author:
Benjamin Sigg

Nested Class Summary
 class DockFrontend.DockInfo
          Information about a Dockable.
 class DockFrontend.Hider
          An object which is action and ActionGuard at the same time.
static class DockFrontend.RootInfo
          Stores information about a root-station.
 
Field Summary
static String DOCKABLE_KEY_PREFIX
          prefix used for Dockables when creating a new PredefinedDockSituation
static Path FRONTEND_EXTENSION
          Name of an DockFrontendExtension for the DockFrontend
static PropertyKey<KeyStroke> HIDE_ACCELERATOR
          This KeyStore calls hide(Dockable) for the currently selected Dockable.
static String ROOT_KEY_PREFIX
          prefix used for roots when creating a new PredefinedDockSituation
 
Constructor Summary
DockFrontend()
          Constructs a new frontend, creates a new controller.
DockFrontend(DockController controller)
          Constructs a new frontend.
DockFrontend(DockController controller, Window owner)
          Constructs a new frontend, tries to set up a ScreenDockStationFactory and sets the root window of controller to owner.
DockFrontend(DockController controller, WindowProvider owner)
          Constructs a new frontend, tries to set up a ScreenDockStationFactory and sets the root window of controller to owner.
DockFrontend(Window owner)
          Constructs a new frontend, creates a new controller.
DockFrontend(WindowProvider owner)
          Constructs a new frontend, creates a new controller.
 
Method Summary
 void addDockable(String id, Dockable dockable)
          Adds a Dockable to this frontend.
 void addEmpty(String name)
          Adds the name of a Dockable whose properties should be stored in this frontend even if the Dockable itself is not registered.
Note that this can add "empty infos" automatically when calling setSetting(Setting, boolean) and information is found that is not associated with any Dockable, but whose key passes the methods of MissingDockableStrategy.
 void addFrontendListener(DockFrontendListener listener)
          Adds a listener to this frontend.
 void addRepresentative(DockElementRepresentative representative)
          Adds a representative for some DockElement.
 void addRoot(DockStation station, String name)
          Deprecated. replaced by addRoot(String, DockStation), since name is used as key in a map it should come first
 void addRoot(String id, DockStation station)
          Adds a root to this frontend.
 void addVetoableListener(VetoableDockFrontendListener listener)
          Adds listener to this frontend.
protected  void clean(DockSituationIgnore ignore)
          Removes all child-parent relations expect the ones filtered out by ignore.
protected  void clean(DockStation station, DockSituationIgnore ignore)
          Removes recursively all children from station, but only if the children are not filtered by ignore.
protected  DockFrontend.Hider createHider()
          Creates the action that is added to all known dockables, and which is called the "close"-action.
 PropertyTransformer createPropertyTransformer()
          Creates a new PropertyTransformer that can be used to read and write DockablePropertys that are associated with this DockFrontend.
protected  Setting createSetting()
          Creates a bag that contains all information needed to describe the current set of properties.
 boolean delete(String name)
          Deletes the setting with the given name.
 int deleteAll()
          Deletes all settings known to this frontend, this method is equivalent of calling delete(String) with all known names for settings.
protected  void fireAdded(Dockable dockable)
          Invokes the method DockFrontendListener.added(DockFrontend, Dockable) on all listeners.
protected  void fireAllHidden(Dockable dockable, Set<Dockable> processed)
          Invokes the method DockFrontendListener.hidden(DockFrontend, Dockable) on all listeners for dockable and all its children.
protected  void fireAllShown(Dockable dockable, Set<Dockable> processed)
          Invokes the method DockFrontendListener.shown(DockFrontend, Dockable) on all listeners for dockable and all its children.
protected  void fireDeleted(String name)
          Invokes the method DockFrontendListener.deleted(DockFrontend, String) on all listeners.
protected  void fireHidden(Dockable dockable)
          Invokes the method DockFrontendListener.hidden(DockFrontend, Dockable) on all listeners.
protected  void fireHideable(Dockable dockable, boolean value)
          Invokes the method DockFrontendListener.hideable(DockFrontend, Dockable, boolean) on all listeners.
protected  void fireLoaded(String name)
          Invokes the method DockFrontendListener.loaded(DockFrontend, String) on all listeners.
protected  void fireRead(String name)
          Invokes the method DockFrontendListener.read(DockFrontend, String) on all listeners.
protected  void fireRemoved(Dockable dockable)
          Invokes the method DockFrontendListener.removed(DockFrontend, Dockable) on all listeners.
protected  void fireSaved(String name)
          Invokes the method DockFrontendListener.saved(DockFrontend, String) on all listeners.
protected  void fireShown(Dockable dockable)
          Invokes the method DockFrontendListener.shown(DockFrontend, Dockable) on all listeners.
 DockController getController()
          Gets the controller which is used by this frontend.
 String getCurrentSetting()
          Gets the name of the setting which was loaded or saved the last time.
 DockStation getDefaultStation()
          Gets the default station of this frontend.
 Dockable getDockable(String name)
          Gets the Dockable which was added to this frontend with the name name.
 Collection<Dockable> getDockables()
          Deprecated. please use listDockables()
 DockFactory<?,?,?> getDockFactory(String factoryId)
          Searches for a DockFactory which id factoryId.
 DockProperties getDockProperties()
          Gets the set of properties which have a controller-global influence.
 FrontendEntry getFrontendEntry(Dockable dockable)
          Gets all the information known about the registered dockable.
 FrontendEntry getFrontendEntry(String key)
          Gets all the information known about the Dockable with name key.
 DockFrontend.Hider getHider()
          Gets the action which is added to all known Dockables, and which is called the "close"-action.
 DockSituationIgnore getIgnoreForEntry()
          Gets the filter which is used when saving or loading a normal entry.
 DockSituationIgnore getIgnoreForFinal()
          Gets the filter which is applied when saving or loading the final layout at the startup or shutdown of the application.
 Setting getLastAppliedEntrySetting()
          Gets the last Setting that was given to setSetting(Setting, boolean) when the entry-parameter was set to true.
 Setting getLastAppliedFullSetting()
          Gets the last Setting that was given to setSetting(Setting, boolean) when the entry-parameter was set to false.
 LayoutChangeStrategy getLayoutChangeStrategy()
          Gets the current strategy that is used to read Settings by this DockFrontend.
 MissingDockableStrategy getMissingDockable()
          Gets the strategy that is applied for location information of missing Dockables.
 Map<String,Dockable> getNamedDockables()
          Gets an independent map containing all Dockables registered to this frontend.
 String getNameOf(Dockable dockable)
          Searches the name of dockable as it was given to addDockable(String, Dockable).
 WindowProvider getOwner()
          Gets the current provider for the root window.
 DockFrontendPerspective getPerspective(boolean entry)
          Creates and returns a new Perspective which can be used to read, write and convert PerspectiveElements.
 DockFrontendPerspective getPerspective(boolean entry, FrontendPerspectiveCache factory)
          Creates and returns a new Perspective which can be used to read, write and convert PerspectiveElements.
 DockStation getRoot(String name)
          Gets the root with the designated name.
 String[] getRootNames()
          Gets the keys for all the root DockStations known to this frontend.
 DockStation[] getRoots()
          Gets a modifiable array containing all DockStations which are registered as root.
 Setting getSetting(boolean entry)
          Creates a new Setting which describes the current set of properties of this frontend.
 Setting getSetting(String name)
          Gets the Setting which stores locations and other information under the key name.
 Set<String> getSettings()
          Gets a set of the names of all known settings.
 boolean hasLocation(Dockable dockable)
          Tells whether this DockFrontend currently knows where to put dockable.
 boolean hasLocation(String id)
          Tells whether this DockFrontend stores location information for a Dockable with id id.
 void hide(Dockable dockable)
          Makes dockable invisible.
 void hide(Dockable dockable, boolean cancelable)
          Makes dockable invisible.
 boolean isDefaultEntryLayout()
          Gets the default value of isEntryLayout(Dockable).
 boolean isDefaultHideable()
          Gets the default value of setHideable(Dockable, boolean).
 boolean isEmpty(String name)
          Tells whether name denotes an entry that can be empty.
 boolean isEntryLayout(Dockable dockable)
          Tells whether the layout of dockable should be stored for entry Settings.
 boolean isEntryLayout(String id)
          Tells whether the layout of id should be stored for entry Settings.
 boolean isHidden(Dockable dockable)
          Tells whether dockable is hidden or not.
 boolean isHiddenRootStation(DockElement element)
          Tells whether element is a root-station and at the same time a Dockable without parent.
 boolean isHideable(Dockable dockable)
          Tells whether there is a "close"-action for dockable or not.
 boolean isShowHideAction()
          Tells whether the hide-action is shown or not.
 boolean isShown(Dockable dockable)
          Tells whether dockable is visible or not.
 void kill()
          Destroys this DockFrontend, it will no longer be useful but can be removed by the garbage collector.
 List<Dockable> listDockables()
          Gets a list of all Dockables which are registered at this frontend.
 String[] listEmpty(boolean all)
          Gets a list of all keys that are marked as empty.
protected  DockFrontendListener[] listeners()
          Gets an independent array containing all currently registered listeners.
 List<FrontendEntry> listFrontendEntries()
          Gets a list of all informations known of any Dockable that is or might be registered at this frontend.
 Set<Dockable> listShownDockables()
          Gets a set of all Dockable which are known to this frontend and which are visible.
 void load(String name)
          Loads a setting of this frontend.
protected  Setting read(boolean entry, DataInputStream in)
          Calls first createSetting() and then Setting.read(DockSituation, PropertyTransformer, boolean, DataInputStream).
 void read(DataInputStream in)
          Reads the settings of this frontend from in.
 void read(DataInputStream in, boolean keepExistingSettings)
          Reads the settings of this frontend from in.
 SettingsBlop readBlop(DataInputStream in)
          Reads the contents of in using all the factories that are currently installed on this DockFrontend, this method does not change any properties of the frontend.
 void readBlop(SettingsBlop blop, boolean keepExistingSettings)
          Reads and applies the Settings stored in blop.
 SettingsBlop readBlopXML(XElement element)
          Reads the contents of element using all the facotries installed on this DockFrontend, without actually changing any property of this frontend.
protected  Setting readXML(boolean entry, XElement element)
          Calls createSetting() and then Setting.readXML(DockSituation, PropertyTransformer, boolean, XElement).
 void readXML(XElement element)
          Reads the contents of this frontend from an xml element.
 void readXML(XElement element, boolean keepExistingSettings)
          Reads the contents of this frontend from an xml element.
 void registerAdjacentFactory(AdjacentDockFactory<?> factory)
          Registers a factory that stores additional information for a set of Dockables.
 void registerBackupFactory(DockFactory<? extends Dockable,?,?> factory)
          Register a backup factory.
 void registerFactory(DockablePropertyFactory factory)
          Registers a factory to write and read properties.
 void registerFactory(DockFactory<?,?,?> factory)
          Registers a factory to write and read Dockables and DockStations.
 void registerFactory(DockFactory<? extends Dockable,?,?> factory, boolean backup)
          Registers a factory to write and read Dockables and DockStations.
 void remove(Dockable dockable)
          Removes a Dockable which was earlier added to this frontend.
 void removeEmpty(String name)
          Removes the properties of a non existing Dockable and/or changes the flag to store information about the non existing Dockablename to false.
 void removeFrontendListener(DockFrontendListener listener)
          Removes an earlier added listener from this frontend.
 void removeRepresentative(DockElementRepresentative representative)
          Removes representative from this frontend.
 void removeRoot(DockStation station)
          Removes a root from this frontend.
 void removeVetoableListener(VetoableDockFrontendListener listener)
          Removes listener from this frontend.
 void save()
          Saves the current layout under the name of the current setting.
 void save(String name)
          Saves the current layout with the specified name.
 void setCurrentSetting(String setting)
          Sets the name of the current setting.
 void setCurrentSettingName(String setting)
          Changes the name of the current setting.
 void setDefaultEntryLayout(boolean defaultEntryLayout)
          Sets the default value for setEntryLayout(Dockable, boolean).
 void setDefaultHideable(boolean defaultHideable)
          Sets the default setting for setHideable(Dockable, boolean).
 void setDefaultStation(DockStation defaultStation)
          Sets the default station of this frontend.
 void setEntryLayout(Dockable dockable, boolean layout)
          Sets whether the layout of dockable should be stored for entry Settings.
 void setEntryLayout(String id, boolean layout)
          Sets whether the layout of id should be stored for entry Settings.
 void setHideable(Dockable dockable, boolean hideable)
          Sets whether to show add a close-action or not to dockable.
 void setIgnoreForEntry(DockSituationIgnore ignoreForEntry)
          Sets a filter which is applied when saving or loading a normal entry.
 void setIgnoreForFinal(DockSituationIgnore ignoreForFinal)
          Sets the filter which is applied when saving or loading the final layout at the startup or shutdown of the application.
 void setLayoutChangeStrategy(LayoutChangeStrategy strategy)
          Sets the strategy this DockFrontend should use to read Settings.
WARNING: strategies may leave a trail of data, some even stored persistently.
 void setMissingDockableStrategy(MissingDockableStrategy missingDockable)
          Sets the strategy how to deal with location information of Dockables which are missing and which are not marked as empty.
If information passes the strategy, then a new empty info will be added to store it.
 void setOwner(WindowProvider owner)
          Sets the window which is used as root for any dialog, can be null.
 void setSetting(Setting setting, boolean entry)
          Changes the content of all root-stations according to setting.
This method may add new empty infos if it finds information for a non existing, non empty Dockable but whose key passes the methods of MissingDockableStrategy.
 void setSetting(String name, Setting setting)
          Stores the setting setting with the given name.
 void setShowHideAction(boolean show)
          Sets whether to show the hide-action or not.
 void show(Dockable dockable)
          Ensures that dockable is child of a root known to this frontend.
 void show(Dockable dockable, boolean cancelable)
          Ensures that dockable is child of a root known to this frontend.
 void unregisterAdjacentFactory(AdjacentDockFactory<?> factory)
          Removes an additional factory from this frontend.
 void unregisterBackupFactory(DockFactory<?,?,?> factory)
          Removes a backup factory from this frontend.
 void unregisterFactory(DockFactory<?,?,?> factory)
          Removes a factory from this frontend.
 void write(DataOutputStream out)
          Writes all settings of this frontend, including the current layout, into out.
protected  void write(Setting setting, boolean entry, DataOutputStream out)
          Calls Setting.write(DockSituation, PropertyTransformer, boolean, DataOutputStream)
 SettingsBlop writeBlop()
          Stores all the current Settings of this DockFrontend in a new SettingsBlop.
 void writeBlop(SettingsBlop blop, DataOutputStream out)
          Writes the contents of blop into out.
 void writeBlopXML(SettingsBlop blop, XElement element)
          Writes all the Settings of blop into element, this method does use the factories installed on this DockFrontend, but does not change any properties of the frontend.
protected  void writeXML(Setting setting, boolean entry, XElement element)
          Calls Setting.writeXML(DockSituation, PropertyTransformer, boolean, XElement).
 void writeXML(XElement element)
          Writes all properties of this frontend into an xml element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HIDE_ACCELERATOR

public static final PropertyKey<KeyStroke> HIDE_ACCELERATOR
This KeyStore calls hide(Dockable) for the currently selected Dockable.


DOCKABLE_KEY_PREFIX

public static final String DOCKABLE_KEY_PREFIX
prefix used for Dockables when creating a new PredefinedDockSituation

See Also:
Constant Field Values

ROOT_KEY_PREFIX

public static final String ROOT_KEY_PREFIX
prefix used for roots when creating a new PredefinedDockSituation

See Also:
Constant Field Values

FRONTEND_EXTENSION

public static final Path FRONTEND_EXTENSION
Name of an DockFrontendExtension for the DockFrontend

Constructor Detail

DockFrontend

public DockFrontend()
Constructs a new frontend, creates a new controller.


DockFrontend

public DockFrontend(Window owner)
Constructs a new frontend, creates a new controller. Registers a ScreenDockStationFactory, which can only be created if the owner of the dialogs is known.

Parameters:
owner - the owner of the dialogs of a ScreenDockStationFactory, may be null

DockFrontend

public DockFrontend(WindowProvider owner)
Constructs a new frontend, creates a new controller. Registers a ScreenDockStationFactory, which can only be created if the owner of the dialogs is known.

Parameters:
owner - the owner of the dialogs of a ScreenDockStationFactory, may be null

DockFrontend

public DockFrontend(DockController controller)
Constructs a new frontend.

Parameters:
controller - the controller used to store root stations

DockFrontend

public DockFrontend(DockController controller,
                    Window owner)
Constructs a new frontend, tries to set up a ScreenDockStationFactory and sets the root window of controller to owner.

Parameters:
controller - the controller used to store the root stations
owner - the owner of the dialog of a ScreenDockStation, may be null

DockFrontend

public DockFrontend(DockController controller,
                    WindowProvider owner)
Constructs a new frontend, tries to set up a ScreenDockStationFactory and sets the root window of controller to owner.

Parameters:
controller - the controller used to store the root stations
owner - the owner of the dialog of a ScreenDockStation, may be null
Method Detail

getController

public DockController getController()
Gets the controller which is used by this frontend.

Returns:
the controller

setOwner

public void setOwner(WindowProvider owner)
Sets the window which is used as root for any dialog, can be null.

Parameters:
owner - the owning window
See Also:
DockController.setRootWindowProvider(WindowProvider)

getOwner

public WindowProvider getOwner()
Gets the current provider for the root window. Note that this might not be the same as given to setOwner(WindowProvider), however it will return the same value.

Returns:
the provider, never null

kill

public void kill()
Destroys this DockFrontend, it will no longer be useful but can be removed by the garbage collector.


getDockables

@Deprecated
public Collection<Dockable> getDockables()
Deprecated. please use listDockables()

Gets the list of Dockables which are added to this frontend.

Returns:
the Dockables

addFrontendListener

public void addFrontendListener(DockFrontendListener listener)
Adds a listener to this frontend. The listener will recieve notifications if anything changes on this frontend.

Parameters:
listener - the observer

removeFrontendListener

public void removeFrontendListener(DockFrontendListener listener)
Removes an earlier added listener from this frontend.

Parameters:
listener - the observer which will be removed

addVetoableListener

public void addVetoableListener(VetoableDockFrontendListener listener)
Adds listener to this frontend. The listener will be notified when a Dockable will be or is closed.
Note: the listener is only guaranteed to receive events for Dockables that are known to this DockFrontend. It may or may not receive events for other Dockables.

Parameters:
listener - the new listener

removeVetoableListener

public void removeVetoableListener(VetoableDockFrontendListener listener)
Removes listener from this frontend.

Parameters:
listener - the listener to remove

registerFactory

public void registerFactory(DockFactory<?,?,?> factory)
Registers a factory to write and read Dockables and DockStations.

Parameters:
factory - the new factory

getDockFactory

public DockFactory<?,?,?> getDockFactory(String factoryId)
Searches for a DockFactory which id factoryId. This method checks all the factories that were added by registerFactory(DockFactory).

Parameters:
factoryId - the unique identifier of the factory
Returns:
the factory or null

registerFactory

public void registerFactory(DockFactory<? extends Dockable,?,?> factory,
                            boolean backup)
Registers a factory to write and read Dockables and DockStations.

Parameters:
factory - the new factory
backup - if true, then factory is registered as backup factory as well.

registerBackupFactory

public void registerBackupFactory(DockFactory<? extends Dockable,?,?> factory)
Register a backup factory. A backup factory is used to create a Dockable that is expected to be in the cache, but is missing. The new Dockable is automatically added to this frontend.
The difference between a normal and a backup factory is: a normal factory will just create the Dockable, a backup factory will also install the Dockable on the DockFrontend using the identifier the element had when it was saved (this happens automatically).

Parameters:
factory - a new factory

registerAdjacentFactory

public void registerAdjacentFactory(AdjacentDockFactory<?> factory)
Registers a factory that stores additional information for a set of Dockables.

Parameters:
factory - the additional factory, not null

unregisterFactory

public void unregisterFactory(DockFactory<?,?,?> factory)
Removes a factory from this frontend. This method does not remove backup factories.

Parameters:
factory - the factory to remove
See Also:
unregisterBackupFactory(DockFactory)

unregisterBackupFactory

public void unregisterBackupFactory(DockFactory<?,?,?> factory)
Removes a backup factory from this frontend.

Parameters:
factory - the factory to remove

unregisterAdjacentFactory

public void unregisterAdjacentFactory(AdjacentDockFactory<?> factory)
Removes an additional factory from this frontend.

Parameters:
factory - the factory to remove

registerFactory

public void registerFactory(DockablePropertyFactory factory)
Registers a factory to write and read properties. Clients only need this method if they provide a new type of DockStation.

Parameters:
factory - the new factory

addDockable

public void addDockable(String id,
                        Dockable dockable)
Adds a Dockable to this frontend. The frontend provides a "close"-button for dockable. The frontend also assumes that dockable can be reused when reading a setting. That means, that the factory which matches the key of dockable does not create a new instance when reading the preferences of dockable. You should note that the frontend does not support Dockables whose lifespan ends when they are made invisible.

Parameters:
id - the unique name of the Dockable
dockable - the new Dockable
Throws:
IllegalArgumentException - if either of dockable or id is null, or if id is not unique.

setMissingDockableStrategy

public void setMissingDockableStrategy(MissingDockableStrategy missingDockable)
Sets the strategy how to deal with location information of Dockables which are missing and which are not marked as empty.
If information passes the strategy, then a new empty info will be added to store it. Note that setting the strategy does only affect future actions, information already stored or discarded will not be rescued or thrown away.

Parameters:
missingDockable - the new strategy, null is valid and will force this frontend to discard any information.

getMissingDockable

public MissingDockableStrategy getMissingDockable()
Gets the strategy that is applied for location information of missing Dockables.

Returns:
the strategy, never null
See Also:
setMissingDockableStrategy(MissingDockableStrategy)

setLayoutChangeStrategy

public void setLayoutChangeStrategy(LayoutChangeStrategy strategy)
Sets the strategy this DockFrontend should use to read Settings.
WARNING: strategies may leave a trail of data, some even stored persistently. This method should only be called once: directly after this DockFrontend has been created. Clients should always set the same kind of strategy.

Parameters:
strategy - the new strategy, not null

getLayoutChangeStrategy

public LayoutChangeStrategy getLayoutChangeStrategy()
Gets the current strategy that is used to read Settings by this DockFrontend.

Returns:
the strategy, not null

createPropertyTransformer

public PropertyTransformer createPropertyTransformer()
Creates a new PropertyTransformer that can be used to read and write DockablePropertys that are associated with this DockFrontend.

Returns:
the new transformer, created by the current LayoutChangeStrategy

getNamedDockables

public Map<String,Dockable> getNamedDockables()
Gets an independent map containing all Dockables registered to this frontend.

Returns:
the map of Dockables

getDockable

public Dockable getDockable(String name)
Gets the Dockable which was added to this frontend with the name name.

Parameters:
name - the name of a Dockable
Returns:
the element or null

getNameOf

public String getNameOf(Dockable dockable)
Searches the name of dockable as it was given to addDockable(String, Dockable).

Parameters:
dockable - some element whose name is searched
Returns:
the name or null

addRoot

public void addRoot(String id,
                    DockStation station)
Adds a root to this frontend. Only Dockables which are children of a root can be stored. The frontend forwards the roots to its controller (through the add-method). Note that the frontend does not observe its controller and therefore does not know whether there are other roots registered at the controller.
Clients should also provide a default station.

Parameters:
id - the unique name of the station
station - the new station
Throws:
IllegalArgumentException - if station or name is null, or if name is not unique.

addRoot

@Deprecated
public void addRoot(DockStation station,
                               String name)
Deprecated. replaced by addRoot(String, DockStation), since name is used as key in a map it should come first

Adds a root to this frontend. Only Dockables which are children of a root can be stored. The frontend forwards the roots to its controller (through the add-method). Note that the frontend does not observe its controller and therefore does not know whether there are other roots registered at the controller.
Clients should also provide a default station.

Parameters:
station - the new station
name - the unique name of the station
Throws:
IllegalArgumentException - if station or name is null, or if name is not unique.

getRoot

public DockStation getRoot(String name)
Gets the root with the designated name.

Parameters:
name - the name of the root
Returns:
the station or null

getRootNames

public String[] getRootNames()
Gets the keys for all the root DockStations known to this frontend.

Returns:
the keys of all root stations

getRoots

public DockStation[] getRoots()
Gets a modifiable array containing all DockStations which are registered as root.

Returns:
the list of roots

addRepresentative

public void addRepresentative(DockElementRepresentative representative)
Adds a representative for some DockElement. Note that no two representatives can have the same component. If two have the same, then the second one overrides the first one.

Parameters:
representative - the new representative
See Also:
DockController.addRepresentative(DockElementRepresentative)

removeRepresentative

public void removeRepresentative(DockElementRepresentative representative)
Removes representative from this frontend.

Parameters:
representative - the element to remove
See Also:
DockController.removeRepresentative(DockElementRepresentative)

setDefaultStation

public void setDefaultStation(DockStation defaultStation)
Sets the default station of this frontend. The default station is needed to add Dockables whose location could not be stored earlier or whose location has become invalid.

Parameters:
defaultStation - the default station, can be null

getDefaultStation

public DockStation getDefaultStation()
Gets the default station of this frontend. This is either the value of setDefaultStation(DockStation) or a root picked at random.

Returns:
the station, might be null

remove

public void remove(Dockable dockable)
Removes a Dockable which was earlier added to this frontend.

Parameters:
dockable - the element to remove

addEmpty

public void addEmpty(String name)
Adds the name of a Dockable whose properties should be stored in this frontend even if the Dockable itself is not registered.
Note that this can add "empty infos" automatically when calling setSetting(Setting, boolean) and information is found that is not associated with any Dockable, but whose key passes the methods of MissingDockableStrategy.

Parameters:
name - the name of the dockable

removeEmpty

public void removeEmpty(String name)
Removes the properties of a non existing Dockable and/or changes the flag to store information about the non existing Dockablename to false.

Parameters:
name - the empty element to remove

isEmpty

public boolean isEmpty(String name)
Tells whether name denotes an entry that can be empty.

Parameters:
name - some unique identifier
Returns:
true if information about a Dockable name is stored even if the element is null

listEmpty

public String[] listEmpty(boolean all)
Gets a list of all keys that are marked as empty.

Parameters:
all - if true then just all keys are returned, if false then only those keys are returned for which no Dockable is registered.
Returns:
the list of keys marked as empty, may be null
See Also:
addEmpty(String), removeEmpty(String)

removeRoot

public void removeRoot(DockStation station)
Removes a root from this frontend. If the root is the default station, then the default station is set to null.

Parameters:
station - the root to remove

hasLocation

public boolean hasLocation(Dockable dockable)
Tells whether this DockFrontend currently knows where to put dockable.

Parameters:
dockable - the element whose location might be known
Returns:
true if the location of dockable is known

hasLocation

public boolean hasLocation(String id)
Tells whether this DockFrontend stores location information for a Dockable with id id. This method does not check whether there actuall is a visible dockable with the given id.

Parameters:
id - the id of some entry
Returns:
true if there is an entry for id and this entry has a location attached

setIgnoreForEntry

public void setIgnoreForEntry(DockSituationIgnore ignoreForEntry)
Sets a filter which is applied when saving or loading a normal entry.

Parameters:
ignoreForEntry - the filter, can be null

getIgnoreForEntry

public DockSituationIgnore getIgnoreForEntry()
Gets the filter which is used when saving or loading a normal entry.

Returns:
the filter, might be null

setIgnoreForFinal

public void setIgnoreForFinal(DockSituationIgnore ignoreForFinal)
Sets the filter which is applied when saving or loading the final layout at the startup or shutdown of the application.

Parameters:
ignoreForFinal - the filter, can be null

getIgnoreForFinal

public DockSituationIgnore getIgnoreForFinal()
Gets the filter which is applied when saving or loading the final layout at the startup or shutdown of the application.

Returns:
the filter, can be null

getDockProperties

public DockProperties getDockProperties()
Gets the set of properties which have a controller-global influence.

Returns:
the set of properties

getLastAppliedFullSetting

public Setting getLastAppliedFullSetting()
Gets the last Setting that was given to setSetting(Setting, boolean) when the entry-parameter was set to false. This might be null if no setting was yet applied.

Returns:
the setting, can be null

getLastAppliedEntrySetting

public Setting getLastAppliedEntrySetting()
Gets the last Setting that was given to setSetting(Setting, boolean) when the entry-parameter was set to true. This might be null if no setting was yet applied or a non-entry setting was applied.

Returns:
the setting, can be null

getSettings

public Set<String> getSettings()
Gets a set of the names of all known settings.

Returns:
the set of names

getSetting

public Setting getSetting(String name)
Gets the Setting which stores locations and other information under the key name.

Parameters:
name - a key that was used for calling save(String)
Returns:
the setting or null if not found

getCurrentSetting

public String getCurrentSetting()
Gets the name of the setting which was loaded or saved the last time.

Returns:
the name, might be null if no setting was saved yet

setCurrentSetting

public void setCurrentSetting(String setting)
Sets the name of the current setting. If there is already a setting with this name, then this setting is loaded. Otherwise the current setting is saved with the new name.

Parameters:
setting - the name of the new setting

setCurrentSettingName

public void setCurrentSettingName(String setting)
Changes the name of the current setting. This is not a renaming operation, no layout is loaded, removed or renamed, this method only changes the result of getCurrentSetting(). This method does not fire any events as nothing happens.

Parameters:
setting - the name to use, can be null

setSetting

public void setSetting(String name,
                       Setting setting)
Stores the setting setting with the given name.

Parameters:
name - the name of the setting
setting - the new setting, not null

isHidden

public boolean isHidden(Dockable dockable)
Tells whether dockable is hidden or not. A Dockable is hidden if either isHiddenRootStation(DockElement) is true or if isShown(Dockable) is false.

Parameters:
dockable - the element whose state is asked
Returns:
true if dockable is not visible
See Also:
isHiddenRootStation(DockElement)

isShown

public boolean isShown(Dockable dockable)
Tells whether dockable is visible or not. A Dockable is visible if it is or will be registered. A root-station is always visible.

Parameters:
dockable - the element whose state is asked
Returns:
true if dockable is visible
See Also:
isHiddenRootStation(DockElement)

isHiddenRootStation

public boolean isHiddenRootStation(DockElement element)
Tells whether element is a root-station and at the same time a Dockable without parent.

Parameters:
element - the element to check
Returns:
true if element is a root-station and a dockable without parent

setDefaultHideable

public void setDefaultHideable(boolean defaultHideable)
Sets the default setting for setHideable(Dockable, boolean). This default value is stored as soon as the identifier of a Dockable becomes known and further changes of the default value will not affect it.

Parameters:
defaultHideable - the default value
See Also:
setHideable(Dockable, boolean)

isDefaultHideable

public boolean isDefaultHideable()
Gets the default value of setHideable(Dockable, boolean).

Returns:
the default value
See Also:
setDefaultHideable(boolean)

isHideable

public boolean isHideable(Dockable dockable)
Tells whether there is a "close"-action for dockable or not.

Parameters:
dockable - the element whose state is asked, must be known to this frontend.
Returns:
true if dockable has a close-action

setHideable

public void setHideable(Dockable dockable,
                        boolean hideable)
Sets whether to show add a close-action or not to dockable. Changes are affected immediately.

Parameters:
dockable - the element whose state will be changed
hideable - the new state
Throws:
IllegalArgumentException - if dockable is not known to this frontend

setShowHideAction

public void setShowHideAction(boolean show)
Sets whether to show the hide-action or not. That property only affects the elements visible to the user, not the logic how to handle Dockables. This property is useful for clients which supply their own action (which might invoke hide).

Parameters:
show - whether to show the action
See Also:
setHideable(Dockable, boolean)

isShowHideAction

public boolean isShowHideAction()
Tells whether the hide-action is shown or not.

Returns:
true if the action is shown on hideable dockables or false otherwise

setDefaultEntryLayout

public void setDefaultEntryLayout(boolean defaultEntryLayout)
Sets the default value for setEntryLayout(Dockable, boolean). This default value is stored as soon as the identifier of a Dockable becomes known and will not be affected by further changes of the default value.

Parameters:
defaultEntryLayout - whether the contents of Dockables should be stored in entry Settings or not
See Also:
getSetting(boolean)

isDefaultEntryLayout

public boolean isDefaultEntryLayout()
Gets the default value of isEntryLayout(Dockable).

Returns:
the default value

setEntryLayout

public void setEntryLayout(Dockable dockable,
                           boolean layout)
Sets whether the layout of dockable should be stored for entry Settings.

Parameters:
dockable - the element whose state is to be set
layout - the new state
Throws:
IllegalArgumentException - if dockable is not known
See Also:
getSetting(boolean)

setEntryLayout

public void setEntryLayout(String id,
                           boolean layout)
Sets whether the layout of id should be stored for entry Settings.

Parameters:
id - the id of the element whose state is to be changed
layout - the new state
Throws:
IllegalArgumentException - if id is not known
See Also:
getSetting(boolean)

isEntryLayout

public boolean isEntryLayout(Dockable dockable)
Tells whether the layout of dockable should be stored for entry Settings.

Parameters:
dockable - the element whose state is asked
Returns:
the state
Throws:
IllegalArgumentException - if dockable is not known
See Also:
getSetting(boolean)

isEntryLayout

public boolean isEntryLayout(String id)
Tells whether the layout of id should be stored for entry Settings.

Parameters:
id - the identifier of an element whose state is requested
Returns:
the state
Throws:
IllegalArgumentException - if id is not known
See Also:
getSetting(boolean)

show

public void show(Dockable dockable)
Ensures that dockable is child of a root known to this frontend.

Parameters:
dockable - the element which should be made visible
Throws:
IllegalStateException - if the default station is needed but can't be found

show

public void show(Dockable dockable,
                 boolean cancelable)
Ensures that dockable is child of a root known to this frontend.

Parameters:
dockable - the element which should be made visible
cancelable - whether a VetoableDockFrontendListener can cancel the operation or not
Throws:
IllegalStateException - if the default station is needed but can't be found

hide

public void hide(Dockable dockable)
Makes dockable invisible. The location of dockable is saved, and if made visible again, it will reappear at its old location.

Parameters:
dockable - the element which should be hidden

hide

public void hide(Dockable dockable,
                 boolean cancelable)
Makes dockable invisible. The location of dockable is saved, and if made visible again, it will reappear at its old location.

Parameters:
dockable - the element which should be hidden
cancelable - whether a VetoableDockFrontendListener can cancel the operation or not

save

public void save()
Saves the current layout under the name of the current setting.

Throws:
IllegalStateException - if the name of the current setting is null

save

public void save(String name)
Saves the current layout with the specified name.

Parameters:
name - the name for the setting

load

public void load(String name)
Loads a setting of this frontend.

Parameters:
name - the name of the setting
Throws:
IllegalArgumentException - if no setting name could be found

getSetting

public Setting getSetting(boolean entry)
Creates a new Setting which describes the current set of properties of this frontend. The setting contains information about the location of each Dockable.

Parameters:
entry - true if only the information for an ordinary entry should be stored, false if the setting should contain as much information as possible.
Returns:
the setting
See Also:
createSetting()

setSetting

public void setSetting(Setting setting,
                       boolean entry)
Changes the content of all root-stations according to setting.
This method may add new empty infos if it finds information for a non existing, non empty Dockable but whose key passes the methods of MissingDockableStrategy.

Parameters:
setting - a new set of properties
entry - true if only information for an ordinary entry should be extracted, false if as much information as possible should be extracted. The value of this argument should be the same as was used when getSetting(boolean) was called.

getPerspective

public DockFrontendPerspective getPerspective(boolean entry)
Creates and returns a new Perspective which can be used to read, write and convert PerspectiveElements. This method creates a new DefaultFrontendPerspectiveCache.
Note: Please read the documentation of DefaultFrontendPerspectiveCache to learn about the drawbacks of using that class.

Parameters:
entry - Whether the perspective should act as if loading or storing an "normal setting". A normal setting is a setting created by save(String) or by save().
Returns:
the new perspective, not null
See Also:
getPerspective(boolean, FrontendPerspectiveCache)

getPerspective

public DockFrontendPerspective getPerspective(boolean entry,
                                              FrontendPerspectiveCache factory)
Creates and returns a new Perspective which can be used to read, write and convert PerspectiveElements. The new perspective will be set up with the factories known to this frontend and with the entries from elements.
Please note that the new perspective does not contain any information about the current layout of this DockFrontend. Clients can use a Setting to access layout information.

Parameters:
entry - Whether the perspective should act as if loading or storing an "normal setting". A normal setting is a setting created by save(String) or by save().
factory - a factory that will be used to translate DockElements to PerspectiveElements
Returns:
the new perspective, not null
See Also:
getSetting(boolean), getSetting(String), setSetting(Setting, boolean), setSetting(String, Setting)

listShownDockables

public Set<Dockable> listShownDockables()
Gets a set of all Dockable which are known to this frontend and which are visible.

Returns:
the set of the visible elements

listDockables

public List<Dockable> listDockables()
Gets a list of all Dockables which are registered at this frontend.

Returns:
the list of elements

listFrontendEntries

public List<FrontendEntry> listFrontendEntries()
Gets a list of all informations known of any Dockable that is or might be registered at this frontend.

Returns:
all known information. Changes to this list itself will not affect this frontend, changes to the entries however might have effects.

getFrontendEntry

public FrontendEntry getFrontendEntry(String key)
Gets all the information known about the Dockable with name key.

Parameters:
key - some key of a dockable
Returns:
all information known or null if nothing is available

getFrontendEntry

public FrontendEntry getFrontendEntry(Dockable dockable)
Gets all the information known about the registered dockable.

Parameters:
dockable - some dockable that may be registered at this DockFrontend
Returns:
any available information about dockable, null if dockable is unknown to this frontend

clean

protected void clean(DockSituationIgnore ignore)
Removes all child-parent relations expect the ones filtered out by ignore.

Parameters:
ignore - a filter, never null

clean

protected void clean(DockStation station,
                     DockSituationIgnore ignore)
Removes recursively all children from station, but only if the children are not filtered by ignore.

Parameters:
station - a station to clean
ignore - a filter

deleteAll

public int deleteAll()
Deletes all settings known to this frontend, this method is equivalent of calling delete(String) with all known names for settings.

Returns:
the number of settings that were deleted
See Also:
delete(String)

delete

public boolean delete(String name)
Deletes the setting with the given name.

Parameters:
name - the name of the setting to delete
Returns:
true if the setting was deleted, false if the setting was unknown anyway.
See Also:
deleteAll()

write

public void write(DataOutputStream out)
           throws IOException
Writes all settings of this frontend, including the current layout, into out.

Parameters:
out - the stream to write into
Throws:
IOException - if there are any problems

writeBlop

public void writeBlop(SettingsBlop blop,
                      DataOutputStream out)
               throws IOException
Writes the contents of blop into out.

Parameters:
blop - the Settings to write
out - the stream to write into
Throws:
IOException - if there are any problems

write

protected void write(Setting setting,
                     boolean entry,
                     DataOutputStream out)
              throws IOException
Calls Setting.write(DockSituation, PropertyTransformer, boolean, DataOutputStream)

Parameters:
setting - the setting which will be written
entry - whether setting is an ordinary entry, or the finall setting that contains more data.
out - the stream to write into
Throws:
IOException - if an I/O-error occurs

read

public void read(DataInputStream in)
          throws IOException
Reads the settings of this frontend from in. The layout will be changed according to the contents that are read. All existing settings are deleted by this method.

Parameters:
in - the stream to read from
Throws:
IOException - if there are any problems

read

public void read(DataInputStream in,
                 boolean keepExistingSettings)
          throws IOException
Reads the settings of this frontend from in. The layout will be changed according to the contents that are read.

Parameters:
in - the stream to read from
keepExistingSettings - whether to keep or to delete (see deleteAll()) the existing settings.
Throws:
IOException - if there are any problems

readBlop

public SettingsBlop readBlop(DataInputStream in)
                      throws IOException
Reads the contents of in using all the factories that are currently installed on this DockFrontend, this method does not change any properties of the frontend.

Parameters:
in - the stream to read from
Returns:
the Settings that were read
Throws:
IOException - if in cannot be read properbly

read

protected Setting read(boolean entry,
                       DataInputStream in)
                throws IOException
Calls first createSetting() and then Setting.read(DockSituation, PropertyTransformer, boolean, DataInputStream).

Parameters:
entry - whether the set of properties is used as ordinary entry, or contains more data than usuall.
in - the stream to read from
Returns:
the new setting
Throws:
IOException - if an I/O-error occurs
See Also:
createSetting()

writeXML

public void writeXML(XElement element)
Writes all properties of this frontend into an xml element.

Parameters:
element - the element to write into, this method will not change the attributes of element

writeBlopXML

public void writeBlopXML(SettingsBlop blop,
                         XElement element)
Writes all the Settings of blop into element, this method does use the factories installed on this DockFrontend, but does not change any properties of the frontend.

Parameters:
blop - the settings to write
element - the element to write into, this method will not change the attributes of element

writeXML

protected void writeXML(Setting setting,
                        boolean entry,
                        XElement element)
Calls Setting.writeXML(DockSituation, PropertyTransformer, boolean, XElement).

Parameters:
setting - the setting to write
entry - whether setting is an ordinary entry, or the finall setting that contains more data.
element - the xml element to write into, this method does not change the attributes of the entry

readXML

public void readXML(XElement element)
Reads the contents of this frontend from an xml element. All existing settings are deleted (see deleteAll()) by this method.

Parameters:
element - the element to read

readXML

public void readXML(XElement element,
                    boolean keepExistingSettings)
Reads the contents of this frontend from an xml element.

Parameters:
element - the element to read
keepExistingSettings - whether to keep or to delete (see deleteAll()) the existing settings.

readBlopXML

public SettingsBlop readBlopXML(XElement element)
Reads the contents of element using all the facotries installed on this DockFrontend, without actually changing any property of this frontend.

Parameters:
element - the element to read
Returns:
all the layouts stored in element

readXML

protected Setting readXML(boolean entry,
                          XElement element)
Calls createSetting() and then Setting.readXML(DockSituation, PropertyTransformer, boolean, XElement).

Parameters:
entry - whether the set of properties is used as ordinary entry, or contains more data than usuall.
element - the xml element containg the data for the new setting
Returns:
the new setting
See Also:
createSetting()

writeBlop

public SettingsBlop writeBlop()
Stores all the current Settings of this DockFrontend in a new SettingsBlop.

Returns:
the blop that contains all the settings of this frontend

readBlop

public void readBlop(SettingsBlop blop,
                     boolean keepExistingSettings)
Reads and applies the Settings stored in blop.

Parameters:
blop - the settings to read
keepExistingSettings - whether deleteAll() should be called, which would result in deleting all existing Settings, a value of false will call deleteAll()

createHider

protected DockFrontend.Hider createHider()
Creates the action that is added to all known dockables, and which is called the "close"-action.

Returns:
the action

createSetting

protected Setting createSetting()
Creates a bag that contains all information needed to describe the current set of properties.

Returns:
the new bag

getHider

public DockFrontend.Hider getHider()
Gets the action which is added to all known Dockables, and which is called the "close"-action. Clients may use this method set another text, icon, ... to the action.

Returns:
the action

listeners

protected DockFrontendListener[] listeners()
Gets an independent array containing all currently registered listeners.

Returns:
the array of listeners

fireAllHidden

protected void fireAllHidden(Dockable dockable,
                             Set<Dockable> processed)
Invokes the method DockFrontendListener.hidden(DockFrontend, Dockable) on all listeners for dockable and all its children.

Parameters:
dockable - the hidden element
processed - Set of Dockables for which the event is already fired, will be modified by this method, can be null

fireHidden

protected void fireHidden(Dockable dockable)
Invokes the method DockFrontendListener.hidden(DockFrontend, Dockable) on all listeners.

Parameters:
dockable - the hidden element

fireAdded

protected void fireAdded(Dockable dockable)
Invokes the method DockFrontendListener.added(DockFrontend, Dockable) on all listeners.

Parameters:
dockable - the added element

fireHideable

protected void fireHideable(Dockable dockable,
                            boolean value)
Invokes the method DockFrontendListener.hideable(DockFrontend, Dockable, boolean) on all listeners.

Parameters:
dockable - the element whose state changed
value - the new state

fireRemoved

protected void fireRemoved(Dockable dockable)
Invokes the method DockFrontendListener.removed(DockFrontend, Dockable) on all listeners.

Parameters:
dockable - the removed element

fireAllShown

protected void fireAllShown(Dockable dockable,
                            Set<Dockable> processed)
Invokes the method DockFrontendListener.shown(DockFrontend, Dockable) on all listeners for dockable and all its children.

Parameters:
dockable - the shown element
processed - Set of Dockables whose event is already fired, will be modified by this method, can be null

fireShown

protected void fireShown(Dockable dockable)
Invokes the method DockFrontendListener.shown(DockFrontend, Dockable) on all listeners.

Parameters:
dockable - the shown element

fireSaved

protected void fireSaved(String name)
Invokes the method DockFrontendListener.saved(DockFrontend, String) on all listeners.

Parameters:
name - the name of the saved setting

fireLoaded

protected void fireLoaded(String name)
Invokes the method DockFrontendListener.loaded(DockFrontend, String) on all listeners.

Parameters:
name - the name of the loaded setting

fireRead

protected void fireRead(String name)
Invokes the method DockFrontendListener.read(DockFrontend, String) on all listeners.

Parameters:
name - the name of the read setting

fireDeleted

protected void fireDeleted(String name)
Invokes the method DockFrontendListener.deleted(DockFrontend, String) on all listeners.

Parameters:
name - the name of the deleted setting