bibliothek.gui.dock.common.perspective
Class CPerspective

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

• Neither single- nor multiple-dockables need to be registered.
• Any root-CStation used by a CControl needs to be registered using addRoot(CStationPerspective)

Author:

Benjamin Sigg

Constructor Summary

CPerspective(CControlAccess control)
Creates a new perspective

Method Summary

void	addRoot(CStationPerspective station) Deprecated. use addStation(CStationPerspective) instead
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.
CStationPerspective	getRoot(String id) Deprecated. use getStation(String) instead
String[]	getRootKeys() Deprecated. use getStationKeys() instead
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

addRoot

@Deprecated
@Todo(compatibility=BREAK_MINOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_2,
      description="Remove this method")
public void addRoot(CStationPerspective station)

Deprecated. use addStation(CStationPerspective) instead

Adds a new station to this perspective. If a station with name id is already registered, then this station gets replaced.

Parameters:

station - the new station

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.

Parameters:

station - the new station

getRoot

@Deprecated
@Todo(compatibility=BREAK_MINOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_2,
      description="Remove this method")
public CStationPerspective getRoot(String id)

Deprecated. use getStation(String) instead

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

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

getRootKeys

@Deprecated
@Todo(compatibility=BREAK_MINOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_2,
      description="Remove this method")
public String[] getRootKeys()

Deprecated. use getStationKeys() instead

Gets the names of all the stations that were registered

Returns:

the names, 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