bibliothek.gui.dock.common.perspective
Class CPerspective

java.lang.Object
  extended by bibliothek.gui.dock.common.perspective.CPerspective

@Todo(compatibility=COMPATIBLE,
      priority=MAJOR,
      description="remove the warning about modes without perspective")
public class CPerspective
extends Object

A CPerspective is a lightweight, modifiable representation of all Dockables and DockStations handled by a CControl.
When using a CPerspective clients have to be aware of:

Author:
Benjamin Sigg

Constructor Summary
CPerspective(CControlAccess control)
          Creates a new perspective
 
Method Summary
 void addStation(CStationPerspective station)
          Adds a new station to this perspective.
 Iterator<PerspectiveElement> elements()
          Gets an iterator that will visit all the PerspectiveElements of this CPerspective.
 CContentPerspective getContentArea()
          Gets a representation of the default CContentArea.
 CContentPerspective getContentArea(String id)
          Gets a representation of the CContentArea with identifier id.
 CDockablePerspective getDockable(String id)
          Searches for the SingleCDockablePerspective or MultipleCDockablePerspective whose unique identifier is id.
 String[] getDockableKeys()
          Gets all the unique keys for SingleCDockablePerspectives and MultipleCDockablePerspectives.
 LocationModeManagerPerspective getLocationManager()
          Gets the representation of the CLocationModeManager, the representation is responsible for finding out what ExtendedMode and location a CDockablePerspective has.
 CExternalizePerspective getScreenStation()
          Gets the CStationPerspective for the station that represents free floating dockables.
 CStationPerspective getStation(String id)
          Gets the station which was registered with the unique identifier id.
 String[] getStationKeys()
          Gets the names of all the stations that were registered
 void putDockable(CDockablePerspective dockable)
          Stores dockable in the list of known dockables.
 CDockablePerspective removeDockable(String key)
          Removes the dockable with unique key key from the list of known dockables.
 void shrink()
          Searches all occurances of a ShrinkablePerspectiveStation and calls shrink on them.
 Location storeLocation(CDockablePerspective dockable)
          Determines the current location of dockable and stores that location in a map using the ExtendedMode of the Location as key.
 void storeLocations()
          Stores the current location of all CDockablePerspectives currently known to this CPerspective.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CPerspective

public CPerspective(CControlAccess control)
Creates a new perspective

Parameters:
control - the owner of this perspective
Method Detail

getLocationManager

public LocationModeManagerPerspective getLocationManager()
Gets the representation of the CLocationModeManager, the representation is responsible for finding out what ExtendedMode and location a CDockablePerspective has.

Returns:
the location manager, not null

storeLocations

public void storeLocations()
Stores the current location of all CDockablePerspectives currently known to this CPerspective. The location is stored in the LocationHistory of each dockable.


storeLocation

public Location storeLocation(CDockablePerspective dockable)
Determines the current location of dockable and stores that location in a map using the ExtendedMode of the Location as key. If the user later clicks on one of the buttons like "minimize" or "externalize" this location information is read and applied.
Also stores the dockables itself, if they are removed from their parents the perspective still knows of their existence

Parameters:
dockable - the element whose location should be stored
Returns:
the location that was stored or null if the location of dockable could not be determined

addStation

public void addStation(CStationPerspective station)
Adds a new station to this perspective. If a station with name id is already registered, then this station gets replaced.
WARNING: the framework will not automatically create a CStation. The client needs to register a SingleCDockableFactory in order to create the station when it is missing.

Parameters:
station - the new station

getStation

public CStationPerspective getStation(String id)
Gets the station which was registered with the unique identifier id.

Parameters:
id - some unique identifier
Returns:
the station associated with id, can be null

getDockable

public CDockablePerspective getDockable(String id)
Searches for the SingleCDockablePerspective or MultipleCDockablePerspective whose unique identifier is id. This method requires a call to storeLocations() before it will return any results.

Parameters:
id - the unique identifier of a dockable, after CControlRegister.toSingleId(String) or CControlRegister.toMultiId(String) has been applied.
Returns:
the stored dockable, null if id is unknown or if storeLocations() was not executed

getDockableKeys

public String[] getDockableKeys()
Gets all the unique keys for SingleCDockablePerspectives and MultipleCDockablePerspectives. For this method to return the correct keys, storeLocations() must have been executed.

Returns:
the keys of all the dockables that are currently known

removeDockable

public CDockablePerspective removeDockable(String key)
Removes the dockable with unique key key from the list of known dockables. If the dockable is still part of the tree, and storeLocations() is called, then the dockable is reinserted into the list.

Parameters:
key - the unique identifier of the element to remove
Returns:
the element that was removed

putDockable

public void putDockable(CDockablePerspective dockable)
Stores dockable in the list of known dockables. This allows clients to add "invisible" dockables: CDockables which are not yet visible but which already have some location information stored.

Parameters:
dockable - the new element, not null

getStationKeys

public String[] getStationKeys()
Gets the names of all the stations that were registered

Returns:
the names, not null

getContentArea

public CContentPerspective getContentArea()
Gets a representation of the default CContentArea. If there are no stations for the perspective, then the missing stations are automatically added to this perspective.

Returns:
the area

getContentArea

public CContentPerspective getContentArea(String id)
Gets a representation of the CContentArea with identifier id. If there are no stations for the perspective, then the missing stations are automatically added to this perspective.

Parameters:
id - the unique identifier of the area
Returns:
the area

getScreenStation

public CExternalizePerspective getScreenStation()
Gets the CStationPerspective for the station that represents free floating dockables. This is equivalent of calling getRoot( CControl.EXTERNALIZED_STATION_ID ).

Returns:
the station or null if there is no station registered with key CControl.EXTERNALIZED_STATION_ID
Throws:
ClassCastException - if the station named CControl.EXTERNALIZED_STATION_ID is not of type CExternalizePerspective

shrink

public void shrink()
Searches all occurances of a ShrinkablePerspectiveStation and calls shrink on them.


elements

public Iterator<PerspectiveElement> elements()
Gets an iterator that will visit all the PerspectiveElements of this CPerspective. The iterator does not check whether this perspective is modified while it is in use.

Returns:
the iterator over all elements