bibliothek.gui.dock.station.split
Class SplitNode

java.lang.Object
  extended by bibliothek.gui.dock.station.split.SplitNode
Direct Known Subclasses:
Placeholder, VisibleSplitNode

public abstract class SplitNode
extends Object

The internal representation of a SplitDockStation is a tree. The subclasses of SplitNode build this tree.

Author:
Benjamin Sigg

Field Summary
protected  double height
          Bounds of this node on the station
protected  double width
          Bounds of this node on the station
protected  double x
          Bounds of this node on the station
protected  double y
          Bounds of this node on the station
 
Constructor Summary
protected SplitNode(SplitDockAccess access, long id)
          Creates a new SplitNode.
 
Method Summary
static boolean above(double x1, double y1, double x2, double y2, double x, double y)
          Calculates whether the point x/y lies above the line going through x1/y1 and x2/y2.
 void addPlaceholder(Path placeholder)
          Stores an additional placeholder in this node.
protected  Leaf create(Dockable dockable, long id)
          Creates a leaf for dockable.
protected  SplitNode create(SplitDockTree.Key key, boolean checkValidity, Map<Leaf,Dockable> linksToSet)
          Creates a new node using the contents of key.
 Leaf createLeaf(long id)
          Creates a new Leaf
 Node createNode(long id)
          Creates a new Node.
 Placeholder createPlaceholder(long id)
          Creates a new Placeholder calling SplitDockAccess.createPlaceholder(long)
 void delete(boolean shrink)
          Removes this node from its parent, if there is a parent.
protected  void ensureIdUnique()
          Recursively visits all children of this SplitNode and ensures that no node has the same unique id.
protected  void ensureIdUniqueAsync()
          Schedules a call to ensureIdUnique() of the Root node.
abstract  void evolve(SplitDockTree.Key key, boolean checkValidity, Map<Leaf,Dockable> linksToSet)
          Creates or replaces children according to the values found in key.
protected  SplitDockAccess getAccess()
          Gets access to the owner-station
 Rectangle getBounds()
          Gets the size and location of this node in pixel where the point 0/0 is equal to the point 0/0 on the owner-station.
abstract  SplitNode getChild(int location)
          Gets the child at location.
abstract  int getChildLocation(SplitNode child)
          Gets the location of a child.
abstract  Node getDividerNode(int x, int y)
          Gets the Node whose divider area contains the point x/y.
 double getHeight()
          Gets the relative height of this node in relation to the owner-station.
 long getId()
          Gets the (hopefully) unique id of this node.
abstract  Leaf getLeaf(Dockable dockable)
          Gets the leaf which represents dockable.
abstract  int getMaxChildrenCount()
          Gets the maximal number of children this node can have.
abstract  Dimension getMinimumSize()
          Gets the minimal size of this node.
 SplitNode getParent()
          Gets the parent of this node.
 PlaceholderMap getPlaceholderMap()
          Gets placeholder information of a child DockStation.
 SplitNode getPlaceholderNode(Path placeholder)
          Searches and returns the first SplitNode which contains placeholder.
 Path[] getPlaceholders()
          Gets all the keys that are stored in this placeholder
abstract  Dimension getPreferredSize()
          Gets the preferred size of this node.
abstract  PutInfo getPut(int x, int y, double factorW, double factorH, Dockable drop)
          Determines where to drop the Dockable drop if the mouse is at location x/y.
 Root getRoot()
          Gets the root of the tree in which this node is
 Dimension getSize()
          Gets the size of this node in pixel.
 SplitDockStation getStation()
          Gets the station this node belongs to.
 int getTotalChildrenCount()
          Counts the total number of children of this node, the total number of children is the total number of nodes and leafes in the tree below this node, excluding this node.
abstract  SplitNode getVisible()
          Gets the root of a subtree such that the root is visible and such that the is the uppermost visible node.
 double getWidth()
          Gets the relative width of this node in relation to the owner-station.
 double getX()
          Gets the relative x-coordinate of this node on the owner-station.
 double getY()
          Gets the relative y-coordinate of this node on the owner-station.
 boolean hasPlaceholder(Path placeholder)
          Tells whether this node contains placeholder.
 boolean hasPlaceholders()
          Tells whether this node is associated with at least one placeholder.
abstract  boolean insert(SplitDockPathProperty property, int depth, Dockable dockable)
          If there are elements left in property, then the next node is to be read and the insert-method of the matching child to be called.
If there are no children, then dockable has to be inserted as new child.
Otherwise this element is to be replaced by a node containing this and the a leaf with dockable.
Subclasses may wary this scheme in order to optimize or to find a better place for the dockable.
abstract  boolean insert(SplitDockPlaceholderProperty property, Dockable dockable)
          Recursively searches for a node or leaf that uses the placeholder specified by property and inserts the dockable there.
 double intersection(SplitDockProperty property)
          Calculates how much of the rectangle given by the property lies inside this node and how much of this node lies in the rectangle.
abstract  boolean isInOverrideZone(int x, int y, double factorW, double factorH)
          Tells whether the coordinates x/y lie inside the override-zone of the SplitDockStation or not.
abstract  boolean isOfUse()
          Tells whether this node still has any use or can safely be removed from the tree
abstract  boolean isVisible()
          Tells whether this node (or one of this children) contains element that are visible to the user.
 void movePlaceholderMap(SplitNode destination)
          Moves the current PlaceholderMap to destination, overriding its old value.
 PutInfo.Put relativeSidePut(double kx, double ky)
          Calculates on which side of the node the point kx/ky lies.
 boolean removePlaceholder(Path placeholder)
          Removes a placeholder from this node.
 void removePlaceholders(Set<Path> placeholders)
          Removes all placeholders in placeholders from this node
 void replace(SplitNode node)
          Replaces this node with node.
 void setBounds(double x, double y, double width, double height, double factorW, double factorH, boolean updateComponentBounds)
          Updates the bounds of this node.
abstract  void setChild(SplitNode child, int location)
          Adds a child to this node at a given location.
 void setParent(SplitNode parent)
          Sets the parent of this node.
 void setPlaceholderMap(PlaceholderMap placeholderMap)
          Sets information about the placeholders of a DockStation that was child of this node.
 void setPlaceholders(Path[] placeholders)
          Sets all the placeholders of this node
abstract
<N> N
submit(SplitTreeFactory<N> factory)
          Writes the contents of this node into a new tree create by factory.
 String toString()
           
abstract  void toString(int tabs, StringBuilder out)
          Writes some contents of this node into out.
protected  void treeChanged()
          Called if a child of this node changed.
 void updateBounds(double x, double y, double width, double height, double factorW, double factorH, boolean updateComponentBounds)
          Updates the bounds of this node.
abstract  void visit(SplitNodeVisitor visitor)
          Invokes one of the methods of the visitor for every child in the subtree with this as root.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

x

protected double x
Bounds of this node on the station


y

protected double y
Bounds of this node on the station


width

protected double width
Bounds of this node on the station


height

protected double height
Bounds of this node on the station

Constructor Detail

SplitNode

protected SplitNode(SplitDockAccess access,
                    long id)
Creates a new SplitNode.

Parameters:
access - the access to the owner of this node. Must not be null
id - the unique id of this node, -1 indicates that the id must be created
Method Detail

treeChanged

protected void treeChanged()
Called if a child of this node changed.


getStation

public SplitDockStation getStation()
Gets the station this node belongs to.

Returns:
the station

getPlaceholders

public Path[] getPlaceholders()
Gets all the keys that are stored in this placeholder

Returns:
all the keys

addPlaceholder

public void addPlaceholder(Path placeholder)
Stores an additional placeholder in this node. Nothing happens if placeholder is already known to this node.

Parameters:
placeholder - the additional placeholder

hasPlaceholders

public boolean hasPlaceholders()
Tells whether this node is associated with at least one placeholder.

Returns:
whether there is at least one placeholder

hasPlaceholder

public boolean hasPlaceholder(Path placeholder)
Tells whether this node contains placeholder.

Parameters:
placeholder - the placeholder to search
Returns:
true if placeholder was found

setPlaceholders

public void setPlaceholders(Path[] placeholders)
Sets all the placeholders of this node

Parameters:
placeholders - all the placeholders, can be null or empty

removePlaceholder

public boolean removePlaceholder(Path placeholder)
Removes a placeholder from this node.

Parameters:
placeholder - the placeholder to remove
Returns:
true if the placeholder was removed

removePlaceholders

public void removePlaceholders(Set<Path> placeholders)
Removes all placeholders in placeholders from this node

Parameters:
placeholders - the placeholders to remove

setPlaceholderMap

public void setPlaceholderMap(PlaceholderMap placeholderMap)
Sets information about the placeholders of a DockStation that was child of this node.

Parameters:
placeholderMap - the placeholder information, can be null

movePlaceholderMap

public void movePlaceholderMap(SplitNode destination)
Moves the current PlaceholderMap to destination, overriding its old value. The map of this node is set to null

Parameters:
destination - the destination of the map

getPlaceholderMap

public PlaceholderMap getPlaceholderMap()
Gets placeholder information of a child DockStation.

Returns:
the placeholder information, can be null

isOfUse

public abstract boolean isOfUse()
Tells whether this node still has any use or can safely be removed from the tree

Returns:
true if this node has to remain in the tree, false otherwise

replace

public void replace(SplitNode node)
Replaces this node with node. Does nothing if this node has no parent.

Parameters:
node - the replacement, not null

delete

public void delete(boolean shrink)
Removes this node from its parent, if there is a parent. The subtree remains intact and no Dockables are removed from the station.

Parameters:
shrink - whether this node should attempt to shrink the tree such that no holes are left after this node was deleted

createLeaf

public Leaf createLeaf(long id)
Creates a new Leaf

Parameters:
id - the unique identifier of the new leaf, can be -1
Returns:
the new leaf

createNode

public Node createNode(long id)
Creates a new Node.

Parameters:
id - the unique identifier of the new node, can be -1
Returns:
the new node

createPlaceholder

public Placeholder createPlaceholder(long id)
Creates a new Placeholder calling SplitDockAccess.createPlaceholder(long)

Parameters:
id - the unique identifier of the new leaf, can be -1
Returns:
the new leaf

getX

public double getX()
Gets the relative x-coordinate of this node on the owner-station. The coordinates are measured as fraction of the size of the owner-station.

Returns:
A value between 0 and 1

getY

public double getY()
Gets the relative y-coordinate of this node on the owner-station. The coordinates are measured as fraction of the size of the owner-station.

Returns:
A value between 0 and 1

getWidth

public double getWidth()
Gets the relative width of this node in relation to the owner-station.

Returns:
a value between 0 and 1

getHeight

public double getHeight()
Gets the relative height of this node in relation to the owner-station.

Returns:
a value between 0 and 1

setParent

public void setParent(SplitNode parent)
Sets the parent of this node.

Parameters:
parent - the new parent, can be null

getParent

public SplitNode getParent()
Gets the parent of this node.

Returns:
the parent, can be null

getId

public long getId()
Gets the (hopefully) unique id of this node.

Returns:
the unique id

ensureIdUniqueAsync

protected void ensureIdUniqueAsync()
Schedules a call to ensureIdUnique() of the Root node. If this method is not called within the EDT, then the id is checked immediatelly. Several calls to this method may be merged into one invocation of ensureIdUnique() for optimization. If there is no Root available, nothing happens.


ensureIdUnique

protected void ensureIdUnique()
Recursively visits all children of this SplitNode and ensures that no node has the same unique id. May change the id of some nodes if necessary.
After this method has completed, no two nodes in the subtree share the same id.


getTotalChildrenCount

public int getTotalChildrenCount()
Counts the total number of children of this node, the total number of children is the total number of nodes and leafes in the tree below this node, excluding this node.

Returns:
the total number of children, can be 0

getAccess

protected SplitDockAccess getAccess()
Gets access to the owner-station

Returns:
the access

isVisible

public abstract boolean isVisible()
Tells whether this node (or one of this children) contains element that are visible to the user.

Returns:
true if this node or one of its children contains a graphical element

getVisible

public abstract SplitNode getVisible()
Gets the root of a subtree such that the root is visible and such that the is the uppermost visible node.

Returns:
the visible root, can be null, this or any child of this node

getMinimumSize

public abstract Dimension getMinimumSize()
Gets the minimal size of this node.

Returns:
the minimal size in pixel

getPreferredSize

public abstract Dimension getPreferredSize()
Gets the preferred size of this node.

Returns:
the preferred size in pixel

updateBounds

public void updateBounds(double x,
                         double y,
                         double width,
                         double height,
                         double factorW,
                         double factorH,
                         boolean updateComponentBounds)
Updates the bounds of this node. If the node represents a Component, then the bounds of the component have to be updated as well.
This method is recursive, it will call updateBounds on the children of this node.

Parameters:
x - the relative x-coordinate
y - the relative y-coordinate
width - the relative width of the node
height - the relative height of the node
factorW - a factor to be multiplied with x and width to get the size of the node in pixel
factorH - a factor to be multiplied with y and height to get the size of the node in pixel
updateComponentBounds - whether to update the bounds of Components that are in the tree. If set to false, then all updates stay within the tree and the graphical user interface is not changed. That can be useful if more than one round of updates is necessary. If in doubt, set this parameter to true.
See Also:
setBounds(double, double, double, double, double, double, boolean)

setBounds

public void setBounds(double x,
                      double y,
                      double width,
                      double height,
                      double factorW,
                      double factorH,
                      boolean updateComponentBounds)
Updates the bounds of this node. If the node represents a Component, then the bounds of the component have to be updated as well. This method is not recursive, it does not call getBounds on the children of this node.

Parameters:
x - the relative x-coordinate
y - the relative y-coordinate
width - the relative width of the node
height - the relative height of the node
factorW - a factor to be multiplied with x and width to get the size of the node in pixel
factorH - a factor to be multiplied with y and height to get the size of the node in pixel
updateComponentBounds - whether to update the bounds of Components that are in the tree. If set to false, then all updates stay within the tree and the graphical user interface is not changed. That can be useful if more than one round of updates is necessary. If in doubt, set this parameter to true.
See Also:
updateBounds(double, double, double, double, double, double, boolean)

getRoot

public Root getRoot()
Gets the root of the tree in which this node is

Returns:
the root or null

getPut

public abstract PutInfo getPut(int x,
                               int y,
                               double factorW,
                               double factorH,
                               Dockable drop)
Determines where to drop the Dockable drop if the mouse is at location x/y.

Parameters:
x - the x-coordinate of the mouse
y - the y-coordinate of the mouse
factorW - a factor to be multiplied with the relative x and width to get the size in pixel.
factorH - a factor to be multiplied with the relative y and height to get the size in pixel.
drop - the Dockable which will be dropped
Returns:
where to drop the dockable or null if the dockable can't be dropped

isInOverrideZone

public abstract boolean isInOverrideZone(int x,
                                         int y,
                                         double factorW,
                                         double factorH)
Tells whether the coordinates x/y lie inside the override-zone of the SplitDockStation or not.

Parameters:
x - the x-coordinate of the mouse
y - the y-coordinate of the mouse
factorW - a factor to be multiplied with the relative x and width to get the size in pixel.
factorH - a factor to be multiplied with the relative y and height to get the size in pixel.
Returns:
true if the station should not allow child-stations to make a drop when the mouse is at x/y

getLeaf

public abstract Leaf getLeaf(Dockable dockable)
Gets the leaf which represents dockable.

Parameters:
dockable - the Dockable whose leaf is searched
Returns:
the leaf or null if no leaf was found

getDividerNode

public abstract Node getDividerNode(int x,
                                    int y)
Gets the Node whose divider area contains the point x/y. Only searches in the subtree with this node as root.

Parameters:
x - the x-coordinate
y - the y-coordinate
Returns:
the Node containing the point, if no Node was found, null is returned

getChildLocation

public abstract int getChildLocation(SplitNode child)
Gets the location of a child.

Parameters:
child - a child of this node
Returns:
the location of child or -1 if the child is unknown

setChild

public abstract void setChild(SplitNode child,
                              int location)
Adds a child to this node at a given location.

Parameters:
child - the new child
location - the location of the child

getMaxChildrenCount

public abstract int getMaxChildrenCount()
Gets the maximal number of children this node can have.

Returns:
the maximal number of children

getChild

public abstract SplitNode getChild(int location)
Gets the child at location.

Parameters:
location - the location of the child
Returns:
the child or null if the location is invalid or if there is no child at the location

visit

public abstract void visit(SplitNodeVisitor visitor)
Invokes one of the methods of the visitor for every child in the subtree with this as root.

Parameters:
visitor - the visitor

evolve

public abstract void evolve(SplitDockTree.Key key,
                            boolean checkValidity,
                            Map<Leaf,Dockable> linksToSet)
Creates or replaces children according to the values found in key. Note that this method does not remove any Dockables from the station. They must be removed explicitly using Leaf.setDockable(Dockable, bibliothek.gui.dock.DockHierarchyLock.Token)

Parameters:
key - the key to read
linksToSet - a map that is to be filled with all new Leafs and their Dockables which are not yet set.
checkValidity - whether to ensure that all new Dockables are acceptable or not.

insert

public abstract boolean insert(SplitDockPathProperty property,
                               int depth,
                               Dockable dockable)
If there are elements left in property, then the next node is to be read and the insert-method of the matching child to be called.
If there are no children, then dockable has to be inserted as new child.
Otherwise this element is to be replaced by a node containing this and the a leaf with dockable.
Subclasses may wary this scheme in order to optimize or to find a better place for the dockable.

Parameters:
property - a list of nodes
depth - the index of the node that corresponds to this
dockable - the element to insert
Returns:
true if the element was inserted, false otherwise

insert

public abstract boolean insert(SplitDockPlaceholderProperty property,
                               Dockable dockable)
Recursively searches for a node or leaf that uses the placeholder specified by property and inserts the dockable there. Also removes the placeholder from this node.

Parameters:
property - the placeholder to search
dockable - the new element
Returns:
true if the element was inserted, false otherwise

getPlaceholderNode

public SplitNode getPlaceholderNode(Path placeholder)
Searches and returns the first SplitNode which contains placeholder.

Parameters:
placeholder - the placeholder to search
Returns:
the node containing placeholder or null

submit

public abstract <N> N submit(SplitTreeFactory<N> factory)
Writes the contents of this node into a new tree create by factory.

Type Parameters:
N - the type of element the factory will create
Parameters:
factory - the factory transforming the elements of the tree into a new form.
Returns:
the representation of this node

toString

public String toString()
Overrides:
toString in class Object

toString

public abstract void toString(int tabs,
                              StringBuilder out)
Writes some contents of this node into out.

Parameters:
tabs - the number of tabs that should be added before the text if a new line is necessary.
out - the container to write into

getSize

public Dimension getSize()
Gets the size of this node in pixel.

Returns:
the size of the node

getBounds

public Rectangle getBounds()
Gets the size and location of this node in pixel where the point 0/0 is equal to the point 0/0 on the owner-station. This method calculates these values anew, clients interested in the current bounds should use VisibleSplitNode.getCurrentBounds().

Returns:
the size and location

create

protected Leaf create(Dockable dockable,
                      long id)
Creates a leaf for dockable. This method only creates the leaf, but does not connect leaf and dockable.

Parameters:
dockable - the element to put into a leaf
id - the unique identifier of the new leaf, can be -1
Returns:
the new leaf or null if the leaf would not be valid

create

protected SplitNode create(SplitDockTree.Key key,
                           boolean checkValidity,
                           Map<Leaf,Dockable> linksToSet)
Creates a new node using the contents of key.

Parameters:
key - the key to read
checkValidity - whether to ensure that all new Dockables are acceptable or not.
linksToSet - a map that will be filled up with new Leafs whose Dockables have not yet been set
Returns:
the new node

intersection

public double intersection(SplitDockProperty property)
Calculates how much of the rectangle given by the property lies inside this node and how much of this node lies in the rectangle. The result is a value between 0 and 1 which is 1 only if this node and the rectangle are identical. The result is 0 if they do not have a shared area.

Parameters:
property - the property that gives a rectangle
Returns:
Area of intersection divided by the maxima of the area of the rectangle and of this node.

relativeSidePut

public PutInfo.Put relativeSidePut(double kx,
                                   double ky)
Calculates on which side of the node the point kx/ky lies.

Parameters:
kx - the relative x-coordinate of the point
ky - the relative y-coordinate of the point
Returns:
One side of the node

above

public static boolean above(double x1,
                            double y1,
                            double x2,
                            double y2,
                            double x,
                            double y)
Calculates whether the point x/y lies above the line going through x1/y1 and x2/y2.

Parameters:
x1 - the x-coordinate of the first point on the line
y1 - the y-coordinate of the first point on the line
x2 - the x-coordinate of the second point on the line
y2 - the y-coordinate of the second point on the line
x - the x-coordinate of the point which may be above the line
y - the y-coordinate of the point which may be above the line
Returns:
true if the point lies above the line, false otherwise