bibliothek.gui.dock.common.perspective
Class CGridPerspective

java.lang.Object
  bibliothek.gui.dock.common.perspective.AbstractCDockablePerspective
      bibliothek.gui.dock.common.perspective.SingleCDockablePerspective
          bibliothek.gui.dock.common.perspective.CGridPerspective

All Implemented Interfaces:

CDockablePerspective, CElementPerspective, CStationPerspective

Direct Known Subclasses:

CWorkingPerspective

public class CGridPerspective
extends SingleCDockablePerspective
implements CStationPerspective

A representation of a CGridArea. If this perspective is loaded with content, then all the coordinates are in a range between 0 and 100.

Author:

Benjamin Sigg

Nested Class Summary

class

CGridPerspective.CommonSplitDockPerspective The type of object that is used by a CGridPerspective as intern representation.

Nested classes/interfaces inherited from class bibliothek.gui.dock.common.perspective.SingleCDockablePerspective

SingleCDockablePerspective.Intern

Constructor Summary

CGridPerspective(String id)
Creates a new, empty perspective.

CGridPerspective(String id, Path typeId)
Creates a new, empty perspective.

CGridPerspective(String id, Path typeId, boolean workingArea)
Creates a new, empty perspective.

Method Summary

CStationPerspective	asStation() Gets this as station, if this is a station.
protected CGridPerspective.CommonSplitDockPerspective	create() Called the first time SingleCDockablePerspective.intern() is called, this method creates the intern representation of this SingleCDockablePerspective.
String	getFactoryID()
PerspectiveDockable	getMaximized() Gets the element that is maximized.
CPerspective	getPerspective() Gets the perspective which presents this station.
PlaceholderMap	getPlaceholders()
SplitDockPerspective.Root	getRoot() Gets access to the intern tree that represents the layout of this area.
Path	getTypeId() Gets the unique id denoting the type of this CStation, this should be the exact same result as CStation.getTypeId() will return.
PerspectiveSplitDockGrid	grid() Allows access to the internal representation of this area as grid.
void	gridAdd(double x, double y, double width, double height, CDockablePerspective... dockables) Adds dockables at location x/y with size width/height to an internal list of pending commands to execute.
void	gridClear() Deletes all pending commands that were collected by the grid* methods.
void	gridDeploy() Removes all children of this area, then executes pending commands that add dockables at specified locations. In particular this method analyzes all the commands that were generated by calls to the grid* methods and merges them into a layout that fits the locations and sizes the client specified as good as possible. If isAutoDeploy() returns true, then this method is called automatically before storing the layout of this area. This method will silently return if the list of pending commands was never accessed directly or indirectly by the client.
void	gridHorizontal(double x1, double x2, double y) Adds a constraint to the algorithm that is executed by gridDeploy(), the constraint tells that there should be a horizontal divider from x1/y to x2/y.
void	gridPlaceholder(double x, double y, double width, double height, CDockablePerspective... dockables) Adds dockables as placeholder at location x/y with size width/height to an internal list of pending commands to execute.
void	gridPrepare() Reads the contents of the root and resets the grid to reflect that root.
void	gridSelect(double x, double y, double width, double height, CDockablePerspective selection) Using location x/y and size width/height as key, this method set the selection in a group of dockables.
void	gridVertical(double x, double y1, double y2) Adds a constraint to the algorithm that is executed by gridDeploy(), the constraint tells that there should be a vertical divider from x/y1 to x/y2.
CGridPerspective.CommonSplitDockPerspective	intern() Gets the internal representation for this element. If CElementPerspective.asDockable() returns a non-null value, then intern().asDockable() must not return null either. If CElementPerspective.asStation() returns a non-null value, then intern().asStation() must not return null either.
boolean	isAutoDeploy() Tells whether gridDeploy() will be called automatically before accessing the tree of Dockables.
boolean	isRoot() Tells whether this is a root station or not.
boolean	isWorkingArea() Tells whether this station will act as a working area.
void	maximize(CDockablePerspective dockable) Maximized dockable on this station.
void	maximize(PerspectiveDockable dockable) Maximized dockable on this station.
protected void	maybeDeploy() Calls gridDeploy(), but only if isAutoDeploy() returns true and if the grid was accessed.
void	setAutoDeploy(boolean autoDeploy) Sets whether gridDeploy() is called automatically by this area before accessing the tree of Dockables.
void	setPerspective(CPerspective perspective) Informs this station by which perspective it is used.
void	setPlaceholders(PlaceholderMap placeholders)
void	setRoot(boolean root) Sets the root station flag.
void	setWorkingArea(boolean workingArea) Sets whether this station should be regarded as a working area or not.

Methods inherited from class bibliothek.gui.dock.common.perspective.SingleCDockablePerspective

asDockable, getUniqueId

Methods inherited from class bibliothek.gui.dock.common.perspective.AbstractCDockablePerspective

getLocationHistory, getParent, getWorkingArea, remove, setWorkingArea

Methods inherited from class java.lang.Object

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

Methods inherited from interface bibliothek.gui.dock.common.perspective.CStationPerspective

getUniqueId

Methods inherited from interface bibliothek.gui.dock.common.perspective.CElementPerspective

asDockable

Constructor Detail

CGridPerspective

public CGridPerspective(String id)

Creates a new, empty perspective.

Parameters:

id - the unique identifier of this perspective

CGridPerspective

public CGridPerspective(String id,
                        Path typeId)

Creates a new, empty perspective.

Parameters:

id - the unique identifier of this perspective

typeId - the type of this station, can be null

CGridPerspective

public CGridPerspective(String id,
                        Path typeId,
                        boolean workingArea)

Creates a new, empty perspective.

Parameters:

id - the unique identifier of this perspective

typeId - the type of this station, can be null

workingArea - whether this station should be treated as working area or not.

Method Detail

isWorkingArea

public boolean isWorkingArea()

Description copied from interface: CStationPerspective

Tells whether this station will act as a working area.

Specified by:

isWorkingArea in interface CStationPerspective

Returns:

whether this station acts as working area

getTypeId

public Path getTypeId()

Description copied from interface: CStationPerspective

Gets the unique id denoting the type of this CStation, this should be the exact same result as CStation.getTypeId() will return.

Specified by:

getTypeId in interface CStationPerspective

Returns:

the type id, can be null

isRoot

public boolean isRoot()

Description copied from interface: CStationPerspective

Tells whether this is a root station or not.

Specified by:

isRoot in interface CStationPerspective

Returns:

the root flag

See Also:

CStationPerspective.setRoot(boolean)

setRoot

public void setRoot(boolean root)

Description copied from interface: CStationPerspective

Sets the root station flag. Setting flag is equivalent of setting the root parameter when calling CControl.addStation(bibliothek.gui.dock.common.CStation, boolean). The location of a Dockable is always relative to its nearest root-station parent.
Please note that the root-flag set by calling CControl.addStation(bibliothek.gui.dock.common.CStation, boolean) will never be overriden by the flag set in the perspective.

Specified by:

setRoot in interface CStationPerspective

setWorkingArea

public void setWorkingArea(boolean workingArea)

Sets whether this station should be regarded as a working area or not. This setting is not stored, it is the clients responsibility to make sure that the matching CStation is or is not a working area.

Parameters:

workingArea - whether this station is to be treated like a working area or not

create

protected CGridPerspective.CommonSplitDockPerspective create()

Description copied from class: SingleCDockablePerspective

Called the first time SingleCDockablePerspective.intern() is called, this method creates the intern representation of this SingleCDockablePerspective.

Overrides:

create in class SingleCDockablePerspective

Returns:

the internal representation of this

intern

public CGridPerspective.CommonSplitDockPerspective intern()

Description copied from interface: CElementPerspective

Gets the internal representation for this element.
If CElementPerspective.asDockable() returns a non-null value, then intern().asDockable() must not return null either.
If CElementPerspective.asStation() returns a non-null value, then intern().asStation() must not return null either.

Specified by:

intern in interface CElementPerspective

Overrides:

intern in class SingleCDockablePerspective

Returns:

the internal representation

setPerspective

public void setPerspective(CPerspective perspective)

Description copied from interface: CStationPerspective

Informs this station by which perspective it is used.

Specified by:

setPerspective in interface CStationPerspective

Parameters:

perspective - the perspective that uses this station or null

getPerspective

public CPerspective getPerspective()

Description copied from interface: CStationPerspective

Gets the perspective which presents this station.

Specified by:

getPerspective in interface CStationPerspective

Returns:

the owner of this station, can be null

maybeDeploy

protected void maybeDeploy()

Calls gridDeploy(), but only if isAutoDeploy() returns true and if the grid was accessed.

gridAdd

public void gridAdd(double x,
                    double y,
                    double width,
                    double height,
                    CDockablePerspective... dockables)

Adds dockables at location x/y with size width/height to an internal list of pending commands to execute. This method does not change the layout of this area, but a call to gridDeploy() will.
Calling this method several times with the same location and size has the same effect as calling it once, but with a bigger array that contains all the dockables that would otherwise be added through many calls.

Parameters:

x - the x-coordinate of dockables, can be any number

y - the y-coordinate of dockables, can be any number

width - the width of dockables, can be any number greater than 0

height - the height of dockables, can be any number greater than 0

dockables - the elements to add, should contain at least one item

See Also:

gridClear(), gridDeploy()

gridPlaceholder

public void gridPlaceholder(double x,
                            double y,
                            double width,
                            double height,
                            CDockablePerspective... dockables)

Adds dockables as placeholder at location x/y with size width/height to an internal list of pending commands to execute. This method does not change the layout of this area, but a call to gridDeploy() will.
Calling this method several times with the same location and size has the same effect as calling it once, but with a bigger array that contains all the dockables that would otherwise be added through many calls.

Parameters:

x - the x-coordinate of dockables, can be any number

y - the y-coordinate of dockables, can be any number

width - the width of dockables, can be any number greater than 0

height - the height of dockables, can be any number greater than 0

dockables - the elements whose placeholders to add, should contain at least one item

Throws:

IllegalArgumentException - if not all dockables have a placeholder

See Also:

gridClear(), gridDeploy()

gridSelect

public void gridSelect(double x,
                       double y,
                       double width,
                       double height,
                       CDockablePerspective selection)

Using location x/y and size width/height as key, this method set the selection in a group of dockables. This method does not change the layout directly, but a call to gridDeploy() will.

Parameters:

x - the x-coordinate of dockables, can be any number

y - the y-coordinate of dockables, can be any number

width - the width of dockables, can be any number greater than 0

height - the height of dockables, can be any number greater than 0

selection - the element that should be selected, must already be in the group

See Also:

gridClear(), gridDeploy()

gridHorizontal

public void gridHorizontal(double x1,
                           double x2,
                           double y)

Adds a constraint to the algorithm that is executed by gridDeploy(), the constraint tells that there should be a horizontal divider from x1/y to x2/y.

Parameters:

x1 - the beginning of the divider

x2 - the end of the divider

y - the vertical position of the divider

gridVertical

public void gridVertical(double x,
                         double y1,
                         double y2)

Adds a constraint to the algorithm that is executed by gridDeploy(), the constraint tells that there should be a vertical divider from x/y1 to x/y2.

Parameters:

x - the horizontal position of the divider

y1 - the beginning of the divider

y2 - the end of the divider

gridClear

public void gridClear()

Deletes all pending commands that were collected by the grid* methods. A call to this method does not change the current layout of this area, but a call to gridDeploy() will.

See Also:

gridDeploy()

gridDeploy

public void gridDeploy()

Removes all children of this area, then executes pending commands that add dockables at specified locations.
In particular this method analyzes all the commands that were generated by calls to the grid* methods and merges them into a layout that fits the locations and sizes the client specified as good as possible.
If isAutoDeploy() returns true, then this method is called automatically before storing the layout of this area.
This method will silently return if the list of pending commands was never accessed directly or indirectly by the client.

See Also:

isAutoDeploy(), gridAdd(double, double, double, double, CDockablePerspective...), gridSelect(double, double, double, double, CDockablePerspective), gridHorizontal(double, double, double), gridVertical(double, double, double), gridClear()

gridPrepare

public void gridPrepare()

Reads the contents of the root and resets the grid to reflect that root. This method is called once during construction of this perspective, it can later be called to reset the perspective.

grid

public PerspectiveSplitDockGrid grid()

Allows access to the internal representation of this area as grid. Changes to the returned object will stored but not change the layout of this area directly, a call to gridDeploy() will change the layout however.

Returns:

the internal grid

See Also:

gridDeploy()

setAutoDeploy

public void setAutoDeploy(boolean autoDeploy)

Sets whether gridDeploy() is called automatically by this area before accessing the tree of Dockables. The default value for this property is true.
Clients have to call gridDeploy() if this property is false in order to execute commands that were collected with the grid* methods.

Parameters:

autoDeploy - whether gridDeploy() is called automatically

isAutoDeploy

public boolean isAutoDeploy()

Tells whether gridDeploy() will be called automatically before accessing the tree of Dockables.

Returns:

whether automatic deployment is active

See Also:

setAutoDeploy(boolean)

getRoot

public SplitDockPerspective.Root getRoot()

Gets access to the intern tree that represents the layout of this area. Clients may alter this tree in any way they like. Please note that if automatic deployment is active, gridDeploy() can be triggered by invoking this method.

Returns:

the root of the intern tree of dockables, null if this area does not have any children

maximize

public void maximize(CDockablePerspective dockable)

Maximized dockable on this station. Please read about the side effects in maximize(PerspectiveDockable).

Parameters:

dockable - the element to maximize, not null

maximize

public void maximize(PerspectiveDockable dockable)

Maximized dockable on this station. Note that maximized elements will be de-maximized by a CControl unless CControl.setRevertToBasicModes(boolean) was switched to false. A call to this method has several side effects that must be cared for:

• If necessary and if auto-deploy is set, gridDeploy() is called.
• If the parent of dockable is not this station, then dockable is removed from the parent and added to this. The location dockable has on its parent is stored and can be used during un-maximization.
• If dockable has no parent, then it is added to this station. No location information is stored. This is no problem for CDockablePerspective as they usually have a history of legal locations associated, but for any other dockable the missing location can lead to strange behavior when un-maximizing.

Parameters:

dockable - the element to maximize

getMaximized

public PerspectiveDockable getMaximized()

Gets the element that is maximized.

Returns:

the maximized child or null

asStation

public CStationPerspective asStation()

Description copied from interface: CElementPerspective

Gets this as station, if this is a station.

Specified by:

asStation in interface CElementPerspective

Overrides:

asStation in class SingleCDockablePerspective

Returns:

this or null

getFactoryID

public String getFactoryID()

getPlaceholders

public PlaceholderMap getPlaceholders()

setPlaceholders

public void setPlaceholders(PlaceholderMap placeholders)