bibliothek.gui.dock.common.perspective
Class CGridPerspective

java.lang.Object
  extended by bibliothek.gui.dock.common.perspective.AbstractCDockablePerspective
      extended by bibliothek.gui.dock.common.perspective.SingleCDockablePerspective
          extended by 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()
           
 List<GridNode<PerspectiveDockable>> getGridNodes()
          Gets all the nodes of the grid.
 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 gridPlaceholder(double x, double y, double width, double height, Path... placeholders)
          Adds placeholders 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.
 void unpack(double x, double y, double width, double height)
          Unpacks the stations (e.g.
 
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.


unpack

public void unpack(double x,
                   double y,
                   double width,
                   double height)
Unpacks the stations (e.g. a stack) that is stored at x,y,width,height. The result is like removing all children and add them again with gridAdd(double, double, double, double, CDockablePerspective...).

Parameters:
x - the x-coordinate of a set of CDockablePerspective, can be any number
y - the y-coordinate of a set of CDockablePerspective, can be any number
width - the width of a set of CDockablePerspective, can be any number greater than 0
height - the height of a set of CDockablePerspective, can be any number greater than 0

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()

gridPlaceholder

public void gridPlaceholder(double x,
                            double y,
                            double width,
                            double height,
                            Path... placeholders)
Adds placeholders 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
placeholders - the placeholders to add, should contain at least one element and no null elements
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()

getGridNodes

public List<GridNode<PerspectiveDockable>> getGridNodes()
Gets all the nodes of the grid. Each node is a set of PerspectiveDockables and their location and size.

Returns:
the nodes, may be empty, is unmodifiable

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:

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)