bibliothek.gui.dock.station.split
Class AbstractSplitDockGrid<D>

java.lang.Object
  bibliothek.gui.dock.station.split.AbstractSplitDockGrid<D>

Type Parameters:

D - the kind of object that represents a Dockable

Direct Known Subclasses:

PerspectiveSplitDockGrid, SplitDockGrid

public abstract class AbstractSplitDockGrid<D>
extends Object

A class that provides a grid for representations of Dockables. The grid can be transformed into a SplitDockTree which has values that would layout the components as they are in the grid. The algorithms used in this class can handle overlapping elements and holes, however results are much better if there are no disturbances in the grid.
There is also a possibility to tell the tree, where dividers should be made.

Author:

Benjamin Sigg

See Also:

SplitDockStation.dropTree(SplitDockTree)

Nested Class Summary

protected static class	AbstractSplitDockGrid.Line Represents a dividing line in the grid.
protected static class	AbstractSplitDockGrid.Node<D> Represents a node in the tree which will be built.

Constructor Summary

AbstractSplitDockGrid()
Creates a new, empty grid.

AbstractSplitDockGrid(String layout, Map<Character,D[]> dockables)
Creates a grid by reading a string which represents a grid.
The argument layout is a string divided by newline "\n".

Method Summary

void	addDockable(double x, double y, double width, double height, D... dockables) Adds dockable to the grid.
void	addHorizontalDivider(double x1, double x2, double y) Adds a horizonal dividing line.
void	addPlaceholders(double x, double y, double width, double height, Path... placeholders) Adds placeholders to the grid.
void	addVerticalDivider(double x, double y1, double y2) Adds a vertical dividing line.
protected abstract D[]	array(int size) Creates a D-array of length size.
protected AbstractSplitDockGrid.Line	bestFittingLine(double x, double y, double w, double h, boolean horizontal, double split) Searches the line that divides the rectangle x, y, width, height best.
protected AbstractSplitDockGrid.Node<D>	combine(AbstractSplitDockGrid.Node<D> a, AbstractSplitDockGrid.Node<D> b) Creates a combination of a and b.
protected double	diff(AbstractSplitDockGrid.Node<D> a, AbstractSplitDockGrid.Node<D> b) Tells whether the two nodes could be merged or not.
protected void	fillTree(SplitDockTree<D> tree) Fills the contents of this grid into tree.
D[]	getDockables(double x, double y, double width, double height) Gets all the dockables that were added to this grid at location x,y,width,height
List<GridNode<D>>	getGridNodes() Gets all the nodes of this grid.
protected List<AbstractSplitDockGrid.Line>	getLines() Gets a list containing all lines of this grid.
protected AbstractSplitDockGrid.Node<D>	getNode(D dockable) Gets the one node containing dockable.
protected List<AbstractSplitDockGrid.Node<D>>	getNodes() Gets a list containing all nodes of this grid.
boolean	isUnpack() Tells whether unpack(double, double, double, double) is called automatically before adding new Dockables to this grid.
protected double	penalty(double x, double y, double w, double h, AbstractSplitDockGrid.Line line) Used by diff to add a penalty if a line hits a rectangle.
void	setPlaceholderMap(double x, double y, double width, double height, PlaceholderMap map) Sets the PlaceholderMap map for the items at the given location.
void	setSelected(double x, double y, double width, double height, D dockable) Marks dockable as selected in the stack of elements that are on position x, y, width, height.
void	setUnpack(boolean unpack) Whether to automatically call unpack(double, double, double, double) before adding any new Dockables to this grid.
protected AbstractSplitDockGrid.Node<D>	tree() Transforms the grid into a tree and returns the root.
protected abstract D[]	unpack(D dockable) Unpacks dockable.
void	unpack(double x, double y, double width, double height) Unpacks any existing DockStation at location x,y,width,height.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractSplitDockGrid

public AbstractSplitDockGrid()

Creates a new, empty grid.

AbstractSplitDockGrid

public AbstractSplitDockGrid(String layout,
                             Map<Character,D[]> dockables)

Creates a grid by reading a string which represents a grid.
The argument layout is a string divided by newline "\n". Every line represents a y-coordinate, the position of a character in a line represents a x-coordinate. The minimal and the maximal x- and y-coordinates for a character is searched, and used to call addDockable, where the Dockable-array is taken from the Map dockables.

Parameters:

layout - the layout, a string divided by newlines

dockables - the Dockables to add, only entries whose character is in the String layout.

Method Detail

setUnpack

public void setUnpack(boolean unpack)

Whether to automatically call unpack(double, double, double, double) before adding any new Dockables to this grid. Default: true.

Parameters:

unpack - whether to unpack automatically

isUnpack

public boolean isUnpack()

Tells whether unpack(double, double, double, double) is called automatically before adding new Dockables to this grid.

Returns:

whether unpack(double, double, double, double) is called

array

protected abstract D[] array(int size)

Creates a D-array of length size.

Parameters:

size - the size of the new array

Returns:

the new array

unpack

public void unpack(double x,
                   double y,
                   double width,
                   double height)

Unpacks any existing DockStation at location x,y,width,height. All children of all DockStations are removed and re-added as if addDockable(double, double, double, double, Object...) would have been called multiple times.

Parameters:

x - the x-coordinate

y - the y-coordinate

width - the width, more than 0

height - the height, more than 0

unpack

protected abstract D[] unpack(D dockable)

Unpacks dockable. Unpacking means converting dockable in something like a DockStation and returning all the children Dockables.

Parameters:

dockable - the dockable to unpack

Returns:

either dockable or all its children

getDockables

public D[] getDockables(double x,
                        double y,
                        double width,
                        double height)

Gets all the dockables that were added to this grid at location x,y,width,height

Parameters:

x - the x-coordinate

y - the y-coordinate

width - the width, more than 0

height - the height, more than 0

Returns:

the dockables, null if there are no dockables at this location

addDockable

public void addDockable(double x,
                        double y,
                        double width,
                        double height,
                        D... dockables)

Adds dockable to the grid. The coordinates are not absolute, only the relative location and size matters. If there are already dockables at the exact same location, then the dockables are stacked.

Parameters:

x - the x-coordinate

y - the y-coordinate

width - the width, more than 0

height - the height, more than 0

dockables - the Dockables to add

addPlaceholders

public void addPlaceholders(double x,
                            double y,
                            double width,
                            double height,
                            Path... placeholders)

Adds placeholders to the grid. The coordinates are not absolute, only the relative location and size matters. If there are already items at the exact same location, then the new placeholders are just added to them.

Parameters:

x - the x-coordinate

y - the y-coordinate

width - the width, more than 0

height - the height, more than 0

placeholders - the new placeholders to add

setPlaceholderMap

public void setPlaceholderMap(double x,
                              double y,
                              double width,
                              double height,
                              PlaceholderMap map)

Sets the PlaceholderMap map for the items at the given location. The map may be used if a DockStation is creating during runtime at this location.

Parameters:

x - the x coordinate

y - the y coordinate

width - the width of the elements

height - the height of the elements

map - the map, can be null

Throws:

IllegalArgumentException - if there is no node at x/y/width/height

setSelected

public void setSelected(double x,
                        double y,
                        double width,
                        double height,
                        D dockable)

Marks dockable as selected in the stack of elements that are on position x, y, width, height. This method requires that add was called with the exact same coordinates and with dockable.

Parameters:

x - the x coordinate

y - the y coordinate

width - the width of the elements

height - the height of the elements

dockable - the element to select, not null

Throws:

IllegalArgumentException - if width or height are below 0, if dockable is null, if add was never called with the arguments

addVerticalDivider

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

Adds a vertical dividing line.

Parameters:

x - the x-coordinate of the line

y1 - the y-coordinate of the first endpoint

y2 - the y-coordinate of the second endpoint

addHorizontalDivider

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

Adds a horizonal dividing line.

Parameters:

x1 - the x-coordinate of the first endpoint

x2 - the x-coordinate of the second endpoint

y - the y-coordinate of the line

fillTree

protected void fillTree(SplitDockTree<D> tree)

Fills the contents of this grid into tree.

Parameters:

tree - the tree to fill

getLines

protected List<AbstractSplitDockGrid.Line> getLines()

Gets a list containing all lines of this grid.

Returns:

the list

getNodes

protected List<AbstractSplitDockGrid.Node<D>> getNodes()

Gets a list containing all nodes of this grid.

Returns:

the nodes

getGridNodes

public List<GridNode<D>> getGridNodes()

Gets all the nodes of this grid. Each node is a set of Ds and their location.

Returns:

the nodes, the list is not modifiable

getNode

protected AbstractSplitDockGrid.Node<D> getNode(D dockable)

Gets the one node containing dockable. This method checks for equality using the == operation.

Parameters:

dockable - the item to search

Returns:

the node or null if not found

tree

protected AbstractSplitDockGrid.Node<D> tree()

Transforms the grid into a tree and returns the root.

Returns:

the root, can be null

combine

protected AbstractSplitDockGrid.Node<D> combine(AbstractSplitDockGrid.Node<D> a,
                                                AbstractSplitDockGrid.Node<D> b)

Creates a combination of a and b.

Parameters:

a - the first node

b - the second node

Returns:

a node which has a and b as children

diff

protected double diff(AbstractSplitDockGrid.Node<D> a,
                      AbstractSplitDockGrid.Node<D> b)

Tells whether the two nodes could be merged or not.

Parameters:

a - the first node

b - the second node

Returns:

how likely the two nodes can be merged, a small result indicates that merging would be a good idea.

bestFittingLine

protected AbstractSplitDockGrid.Line bestFittingLine(double x,
                                                     double y,
                                                     double w,
                                                     double h,
                                                     boolean horizontal,
                                                     double split)

Searches the line that divides the rectangle x, y, width, height best.

Parameters:

x - the x-coordinate of the rectangle

y - the y-coordinate of the rectangle

w - the width of the rectangle

h - the height of the rectangle

horizontal - whether the line should be horizontal or not

split - the preferred value of AbstractSplitDockGrid.Line.alpha.

Returns:

a line or null

penalty

protected double penalty(double x,
                         double y,
                         double w,
                         double h,
                         AbstractSplitDockGrid.Line line)

Used by diff to add a penalty if a line hits a rectangle.

Parameters:

x - the x-coordinate of the rectangle

y - the y-coordinate of the rectangle

w - the width of the rectangle

h - the height of the rectangle

line - the line which may hit the rectangle

Returns:

the penalty, a value that will be added to the result of diff.