bibliothek.gui
Class DockFrontend

java.lang.Object
  extended by bibliothek.gui.DockFrontend

public class DockFrontend
extends java.lang.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.
The frontend has a list of Dockables. It assumes that these Dockables never changes. 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.

Author:
Benjamin Sigg

Nested Class Summary
private  class DockFrontend.DockInfo
          Information about a Dockable.
 class DockFrontend.Hider
          An object which is action and ActionGuard at the same time.
private  class DockFrontend.RootInfo
          Stores information about a root-station.
 
Field Summary
private  DockController controller
          The controller whhere roots are added
private  java.lang.String currentSetting
          The name of the setting which is currently loaded
private  DockStation defaultStation
          The station which is used to add Dockables if no other station is explicitly requested
private  java.util.Map<java.lang.String,DockFrontend.DockInfo> dockables
          The locations of the known Dockables
private  java.util.Set<DockFactory<? extends DockElement>> dockFactories
          A set of factories needed to store Dockables
private  DockFrontend.Hider hider
          An action and actionguard which hides Dockables
private  DockSituationIgnore ignoreForEntry
          A filter for elements which should not be changed when writing or reading a normal setting
private  DockSituationIgnore ignoreForFinal
          A filter for elements which should not be changed when writing or reading the final setting during the startup or shutdown of the application.
private  java.util.List<DockFrontendListener> listeners
          A list of observers
private  java.util.Set<DockablePropertyFactory> propertyFactories
          A set of factories needed to store properties
private  java.util.Map<java.lang.String,DockFrontend.RootInfo> roots
          The roots of this frontend
private  java.util.Map<java.lang.String,byte[]> settings
          A map of all known settings
private  boolean showHideAction
          Tells whether to show the hide-action on hideable dockables or not
 
Constructor Summary
DockFrontend()
          Constructs a new frontend, creates a new controller.
DockFrontend(DockController controller)
          Constructs a new frontend.
DockFrontend(DockController controller, java.awt.Window owner)
          Constructs a new frontend, tries to set up a ScreenDockStationFactory.
DockFrontend(java.awt.Window owner)
          Constructs a new frontend, creates a new controller.
 
Method Summary
 void add(Dockable dockable, java.lang.String name)
          Adds a Dockable to this frontend.
 void addFrontendListener(DockFrontendListener listener)
          Adds a listener to this frontend.
 void addRoot(DockStation station, java.lang.String name)
          Adds a root to this frontend.
protected  void clean(Dockable dockable, DockSituationIgnore ignore)
          Removes dockable from its parent, but only if it is not filtered by ignore.
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 all recursively all children from station, but only if neither the station nor its children are filtered by ignore.
protected  DockFrontend.Hider createHider()
          Creates the action that is added to all known dockables, and which is called the "close"-action.
protected  DockSituation createSituation(boolean entry)
          Invoked every time before the current setting is written into a stream.
protected  PropertyTransformer createTransformer()
          Invoked every time before properties are written or read.
 boolean delete(java.lang.String name)
          Deletes the setting with the given name.
protected  void fireDeleted(java.lang.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 fireLoaded(java.lang.String name)
          Invokes the method DockFrontendListener.loaded(DockFrontend, String) on all listeners.
protected  void fireSaved(java.lang.String name)
          Invokes the method DockFrontendListener.saved(DockFrontend, String) on all listeners.
protected  void fireShowed(Dockable dockable)
          Invokes the method DockFrontendListener.showed(DockFrontend, Dockable) on all listeners.
 DockController getController()
          Gets the controller which is used by this frontend.
 java.lang.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.
 java.util.Collection<Dockable> getDockables()
          Gets the list of Dockables which are added to this frontend.
 DockProperties getDockProperties()
          Gets the set of properties which have a controller-global influence.
 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.
private  DockFrontend.DockInfo getInfo(Dockable dockable)
          Gets the information about dockable.
private  DockFrontend.DockInfo getInfo(java.lang.String name)
          Gets the information for the element with the designated name.
 java.util.Map<java.lang.String,Dockable> getNamedDockables()
          Gets an independent map containing all Dockables registered to this frontend.
private  DockFrontend.RootInfo getRoot(DockStation station)
          Gets information about the root station.
 DockStation getRoot(java.lang.String name)
          Gets the root with the designated name.
 java.util.Set<java.lang.String> getSettings()
          Gets a set of the names of all known settings.
 void hide(Dockable dockable)
          Makes dockable invisible.
 boolean isHidden(Dockable dockable)
          Tells whether dockable is hidden or not.
 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.
protected  DockFrontendListener[] listeners()
          Gets an independent array containing all currently registered listeners.
 java.util.Set<Dockable> listShownDockables()
          Gets a set of all Dockable which are known to this frontend and which are visible.
protected  void load(java.io.DataInputStream in, boolean entry)
          Reads a setting that was earlier converted into a byte-stream.
 void load(java.lang.String name)
          Loads a setting of this frontend.
 void read(java.io.DataInputStream in)
          Reads the settings of this frontend from in.
 void registerFactory(DockablePropertyFactory factory)
          Registers a factory to write and read properties.
 void registerFactory(DockFactory<? extends DockElement> factory)
          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 removeFrontendListener(DockFrontendListener listener)
          Removes an earlier added listener from this frontend.
 void removeRoot(DockStation station)
          Removes a root from this frontend.
 void save()
          Saves the current layout under the name of the current setting.
protected  void save(java.io.DataOutputStream out, boolean entry)
          Writes the current layout as byte-stream into out.
 void save(java.lang.String name)
          Saves the current layout with the specified name.
 void setCurrentSetting(java.lang.String setting)
          Sets the name of the current setting.
 void setDefaultStation(DockStation defaultStation)
          Sets the default station of this frontend.
 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 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 write(java.io.DataOutputStream out)
          Writes all settings of this frontend, including the current layout, into out.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

controller

private DockController controller
The controller whhere roots are added


hider

private DockFrontend.Hider hider
An action and actionguard which hides Dockables


dockables

private java.util.Map<java.lang.String,DockFrontend.DockInfo> dockables
The locations of the known Dockables


defaultStation

private DockStation defaultStation
The station which is used to add Dockables if no other station is explicitly requested


roots

private java.util.Map<java.lang.String,DockFrontend.RootInfo> roots
The roots of this frontend


dockFactories

private java.util.Set<DockFactory<? extends DockElement>> dockFactories
A set of factories needed to store Dockables


propertyFactories

private java.util.Set<DockablePropertyFactory> propertyFactories
A set of factories needed to store properties


currentSetting

private java.lang.String currentSetting
The name of the setting which is currently loaded


settings

private java.util.Map<java.lang.String,byte[]> settings
A map of all known settings


listeners

private java.util.List<DockFrontendListener> listeners
A list of observers


ignoreForEntry

private DockSituationIgnore ignoreForEntry
A filter for elements which should not be changed when writing or reading a normal setting


ignoreForFinal

private DockSituationIgnore ignoreForFinal
A filter for elements which should not be changed when writing or reading the final setting during the startup or shutdown of the application.


showHideAction

private boolean showHideAction
Tells whether to show the hide-action on hideable dockables or not

Constructor Detail

DockFrontend

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


DockFrontend

public DockFrontend(java.awt.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(DockController controller)
Constructs a new frontend.

Parameters:
controller - the controller used to store root stations

DockFrontend

public DockFrontend(DockController controller,
                    java.awt.Window owner)
Constructs a new frontend, tries to set up a ScreenDockStationFactory.

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

getDockables

public java.util.Collection<Dockable> getDockables()
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

registerFactory

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

Parameters:
factory - the new factory

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

add

public void add(Dockable dockable,
                java.lang.String name)
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:
dockable - the new Dockable
name - the unique name of the Dockable
Throws:
java.lang.IllegalArgumentException - if either of dockable or name is null, or if name is not unique.

getNamedDockables

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

Returns:
the map of Dockables

addRoot

public void addRoot(DockStation station,
                    java.lang.String name)
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 observ 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:
java.lang.IllegalArgumentException - if station or name is null, or if name is not unique.

getRoot

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

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

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

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

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

getSettings

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

Returns:
the set of names

getCurrentSetting

public java.lang.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(java.lang.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

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

isHidden

public boolean isHidden(Dockable dockable)
Tells whether dockable is hidden or not.

Parameters:
dockable - the element whose state is asked
Returns:
true if dockable is not visible

isShown

public boolean isShown(Dockable dockable)
Tells whether dockable is visible or not.

Parameters:
dockable - the element whose state is asked
Returns:
true if dockable is visible

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:
java.lang.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

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:
java.lang.IllegalArgumentException - if dockable is not known
java.lang.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
Throws:
java.lang.IllegalArgumentException - if dockable is not known

save

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

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

save

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

Parameters:
name - the name for the setting

save

protected void save(java.io.DataOutputStream out,
                    boolean entry)
             throws java.io.IOException
Writes the current layout as byte-stream into out.

Parameters:
out - the stream to write into
entry - true if just an ordinary setting should be written, false if the final setting should be written.
Throws:
java.io.IOException - if there are any problems

load

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

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

listShownDockables

public java.util.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

load

protected void load(java.io.DataInputStream in,
                    boolean entry)
             throws java.io.IOException
Reads a setting that was earlier converted into a byte-stream.

Parameters:
in - the stream to read
entry - true if the setting is just an ordinary setting, false if a final setting is read.
Throws:
java.io.IOException - if there are any problems

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 all recursively all children from station, but only if neither the station nor its children are filtered by ignore.

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

clean

protected void clean(Dockable dockable,
                     DockSituationIgnore ignore)
Removes dockable from its parent, but only if it is not filtered by ignore. If dockable is a station, clean(DockStation, DockSituationIgnore) should also be called.

Parameters:
dockable - the element to remove from its parent.
ignore - a filter

delete

public boolean delete(java.lang.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.

write

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

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

read

public void read(java.io.DataInputStream in)
          throws java.io.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
Throws:
java.io.IOException - if there are any problems

createSituation

protected DockSituation createSituation(boolean entry)
Invoked every time before the current setting is written into a stream.

Parameters:
entry - true if the situation is used for a regular setting, false if the situation is used as the final setting which will be loaded the next time the application starts.
Returns:
the situation

createTransformer

protected PropertyTransformer createTransformer()
Invoked every time before properties are written or read.

Returns:
a transformer to read or write properties.

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

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

getInfo

private DockFrontend.DockInfo getInfo(Dockable dockable)
Gets the information about dockable.

Parameters:
dockable - the element whose states are asked
Returns:
the states or null

getInfo

private DockFrontend.DockInfo getInfo(java.lang.String name)
Gets the information for the element with the designated name.

Parameters:
name - the name of the element whose states are asked
Returns:
the states or null

getRoot

private DockFrontend.RootInfo getRoot(DockStation station)
Gets information about the root station.

Parameters:
station - a root
Returns:
the information or null

listeners

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

Returns:
the array of listeners

fireHidden

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

Parameters:
dockable - the hidden element

fireShowed

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

Parameters:
dockable - the shown element

fireSaved

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

Parameters:
name - the name of the saved setting

fireLoaded

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

Parameters:
name - the name of the loaded setting

fireDeleted

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

Parameters:
name - the name of the deleted setting