y.layout.organic
Class InteractiveOrganicLayouter

java.lang.Object
  y.layout.organic.InteractiveOrganicLayouter

All Implemented Interfaces:

Layouter

public class InteractiveOrganicLayouter
extends Object
implements Layouter

The InteractiveOrganicLayouter is a special organic layouter that offers functionality to change the laid out graph while the layouter is running. This layouter may be used in a threaded environment. The read-access getCenter(y.base.Node) does not have to be synchronized. The setters (e.g. setCenter(y.base.Node, double, double)) are scheduled and executed at a specific point within the life-cycle of the layouter. If a CopiedLayoutGraph is being laid out, structural changes (node and edge additions/removals) in the original graph are automatically scheduled and executed on the copy. The method addStructureUpdate(Runnable) may be used to schedule a Runnable that is executed in a synchronized context and may safely update the structure of the graph. The layouter can also run in a single-threaded mode that is provided by a startLayoutSingleThreaded(y.layout.LayoutGraph) single threaded context}. The InteractiveOrganicLayouter.SingleThreadContext provides methods to control layout calculation.

See Also:

startLayout(y.layout.LayoutGraph), stop(), stopAndWait(), startLayoutSingleThreaded(y.layout.LayoutGraph), InteractiveOrganicLayouter.SingleThreadContext

Nested Class Summary

static interface

InteractiveOrganicLayouter.SingleThreadContext Context object that provides controls of layout calculation in case the layouter runs single-threaded.

Field Summary

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

InteractiveOrganicLayouter()
Create a new instance of the InteractiveOrganicLayouter.

Method Summary

void	addStructureUpdate(Runnable runnable) Adds a structural update to the queue.
boolean	canLayout(LayoutGraph graph) Returns whether this layouter can layout the given graph.
void	commitPositions() This method writes the calculated positions (represented by the internal data structure of this layouter) to the LayoutGraph.
double	commitPositionsSmoothly(double maxMovement, double factor) This method transfers the calculated positions (represented by the internal data structure of this layouter) to the LayoutGraph.
void	doLayout(LayoutGraph graph) Calculates the layout for the graph.
void	enableOnlyCore() Makes sure that the core of this layouter will not use the usual LayoutStages, like ComponentLayouter, ParallelEdgeLayouter, etc.
YPoint	getCenter(Node node) Return the actual center of the node
double	getCenterX(Node node) Return the actual center of the node.
double	getCenterY(Node node) Return the actual center of the node.
long	getLastWakeupTime() Returns the time when the last wake-up has occurred
long	getMaxTime() Return the maximal time the layouter will run (in milliseconds).
OutputRestriction	getOutputRestriction() Returns the current OutputRestriction instance set for this instance.
double	getQuality() The quality time ratio set.
double	getStress(Node node) Gets the stress for the given node.
double	getWorkingRatio() Returns the actual working ratio.
boolean	isAutomaticStructureUpdateEnabled() Determines whether this algorithm performs automatic structure updates.
boolean	isRunning() Returns whether the layouter is running at the moment.
boolean	isSleeping() Returns whether the layouter is sleeping.
boolean	isStopped() Returns whether the layouter has been stopped.
void	setAutomaticStructureUpdateEnabled(boolean automaticStructureUpdateEnabled) Determines whether this algorithm performs automatic structure updates.
void	setCenter(Node node, double x, double y) Sets the center for the node.
void	setCenterX(Node node, double x) Sets the center of the node.
void	setCenterY(Node node, double y) Sets the center of the node.
void	setInertia(Node node, double inertia) Set the inertia for the node.
void	setMaxTime(long maxTime) Sets the maximal time the layouter will run.
void	setOutputRestriction(OutputRestriction restriction) Sets a restriction on the output generated by this layouter
void	setPreferredEdgeLength(double preferredEdgeLength) Sets the preferred edge length.
void	setPreferredEdgeLength(Edge edge, double newEdgeLength) Sets the preferred edge length for the given edge.
void	setPreferredNodeDistance(double preferredNodeDistance) Sets the preferred node distance.
void	setQuality(double quality) Sets the quality ratio (value between 0.0 and 1.0) The higher this value is, the better will be the quality for the resulting layout but also the needed time.
void	setRadius(Node node, double radius) Sets the radius for the given node
void	setStress(Node node, double stress) Sets the stress for the given node.
void	setWorkingRatio(double workingRatio) Sets the working ratio.
Thread	startLayout(LayoutGraph graph) Calls doLayout(y.layout.LayoutGraph) in a separate, newly started Thread.
InteractiveOrganicLayouter.SingleThreadContext	startLayoutSingleThreaded(LayoutGraph graph) Creates a context object that provides methods to continue and stop the layout calculation.
void	stop() Stops the layouter.
void	stopAndWait() Stops a previously started layout Thread and blocks until the layout is completed.
void	syncStructure() This method synchronizes the CopiedLayoutGraph given as parameter to doLayout(y.layout.LayoutGraph) with the original graph.
void	wakeUp() This method may be called if something has "changed" and the layouter shall restart/continue layout calculation.

Methods inherited from class java.lang.Object

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

Constructor Detail

InteractiveOrganicLayouter

public InteractiveOrganicLayouter()

Create a new instance of the InteractiveOrganicLayouter.

Method Detail

enableOnlyCore

public void enableOnlyCore()

Makes sure that the core of this layouter will not use the usual LayoutStages, like ComponentLayouter, ParallelEdgeLayouter, etc. If you really need this feature, override this method and return silently.

isAutomaticStructureUpdateEnabled

public boolean isAutomaticStructureUpdateEnabled()

Determines whether this algorithm performs automatic structure updates. If set to true this algorithm will register a listener on the graph to be laid out to automatically update internal data structures as soon as the structure of the original graph changes.

The default is false.

Returns:

whether the automatic update feature is enabled

setAutomaticStructureUpdateEnabled

public void setAutomaticStructureUpdateEnabled(boolean automaticStructureUpdateEnabled)

Determines whether this algorithm performs automatic structure updates. If set to true this algorithm will register a listener on the graph to be laid out to automatically update internal data structures as soon as the structure of the original graph changes.

The default is false.

Parameters:

automaticStructureUpdateEnabled - whether to enable automatic updates.

canLayout

public boolean canLayout(LayoutGraph graph)

Returns whether this layouter can layout the given graph.

Specified by:

canLayout in interface Layouter

Returns:

true if the graph may be laid out, false otherwise.

doLayout

public void doLayout(LayoutGraph graph)

Calculates the layout for the graph. The calculated layout is *NOT AUTOMATICALLY APPLIED*. The graph has to be updated with the actual calculated positions automatically.

Attention: It is recommended to use a CopiedLayoutGraph to buffer the original graph. If setAutomaticStructureUpdateEnabled(boolean) is set to true, structural changes to the original graph are automatically transferred to the copy.

 InteractiveOrganicLayouter layouter = new InteractiveOrganicLayouter();
 Graph2D originalGraph = new Graph2D();

 CopiedLayoutGraph copy = new CopiedLayoutGraph( originalGraph );
 layouter.setAutomaticStructureUpdateEnabled( true );
 layouter.doLayout( copy );
 

If an instance of CopiedLayoutGraph is laid out, the setters and getters having a node or edge as parameter may be used with instances from the original graph *or* the copied graph.
This call will not return until stop() is called.

Specified by:

doLayout in interface Layouter

Parameters:

graph - the graph that is laid out

See Also:

startLayout(y.layout.LayoutGraph)

startLayout

public Thread startLayout(LayoutGraph graph)

Calls doLayout(y.layout.LayoutGraph) in a separate, newly started Thread.

Parameters:

graph - the graph to pass on to doLayout(y.layout.LayoutGraph)

Returns:

the Thread that has been created and started.

startLayoutSingleThreaded

public InteractiveOrganicLayouter.SingleThreadContext startLayoutSingleThreaded(LayoutGraph graph)

Creates a context object that provides methods to continue and stop the layout calculation. Note that simply calling this method will not perform any layout. Repeated calls to InteractiveOrganicLayouter.SingleThreadContext.doLayout(long) need to be made in order for the layout calculation to be performed.

Parameters:

graph - the graph that gets layouted.

Returns:

the context object to control layout calculation.

commitPositions

public void commitPositions()

This method writes the calculated positions (represented by the internal data structure of this layouter) to the LayoutGraph.
This method must only be called while the layouter is running isRunning().

 final InteractiveOrganicLayouter layouter = new InteractiveOrganicLayouter();
 new Thread( new Runnable() {
  public void run() {
    layouter.doLayout( copiedGraph );
  }
 } ).start();

 new javax.swing.Timer( 24, new ActionListener() {
  public void actionPerformed( ActionEvent e ) {
    layouter.commitPositions();
  }
 } ).start();
 

There may occur synchronization issues, if doLayout(y.layout.LayoutGraph) is not called using a CopiedLayoutGraph.

commitPositionsSmoothly

public double commitPositionsSmoothly(double maxMovement,
                                      double factor)

This method transfers the calculated positions (represented by the internal data structure of this layouter) to the LayoutGraph.
This method must only be called while the layouter is running isRunning().

The positions are not transferred directly. Instead the nodes are moved towards the calculated position in each step. "Good" values for this method may be about 50 for the maxMovement and about 0.15 as factor (when the positions are updates about 25 times a second).

Parameters:

maxMovement - the maximal distance a node is moved

factor - determines the node movement (movement = factor * distance between calculated and actual location)

Returns:

the biggest movement. This value can be used to estimate the difference between calculated layout and actual positions. If the return value is "0" the calculated layout has been transferred completely.

wakeUp

public void wakeUp()

This method may be called if something has "changed" and the layouter shall restart/continue layout calculation. This is e.g. useful if the layouter is sleeping and some user interaction has occurred.

getLastWakeupTime

public long getLastWakeupTime()

Returns the time when the last wake-up has occurred

Returns:

The time when the last wake-up has occurred

addStructureUpdate

public void addStructureUpdate(Runnable runnable)

Adds a structural update to the queue. The given Runnable will be queued and executed at a specific time. Within this Runnable structural changes (like edge/node removals or adds) may be done. They are synchronized with the layouter. This method should only be used when changes to the structure of the graph are done. Every structural change involves a rebuild of the internal data structure. So "lightweight" changes like modifications of the positions of the nodes should be done using the corresponding methods setCenter(y.base.Node, double, double).

Parameters:

runnable -

stop

public void stop()

Stops the layouter. The layouter will stop after the actual round. This means that the layouter cannot be awakened again.

isStopped

public boolean isStopped()

Returns whether the layouter has been stopped.

Returns:

whether the layouter has been stopped.

isSleeping

public boolean isSleeping()

Returns whether the layouter is sleeping. A sleeping layouter can be awakened using wakeUp() and will continue its work.

Returns:

whether the layouter is sleeping.

isRunning

public boolean isRunning()

Returns whether the layouter is running at the moment.

Returns:

Whether the layouter is running at the moment.

getWorkingRatio

public double getWorkingRatio()

Returns the actual working ratio. The working ratio is the planned ratio of working time to waiting time.

Returns:

the actual working ratio

setWorkingRatio

public void setWorkingRatio(double workingRatio)

Sets the working ratio. The working ratio represents the amount of processor time the layouter tries to grab. If the working ratio is set to 1 the layouter will try to run as fast as possible. Lower values will lead to small breaks after each round.

Parameters:

workingRatio - between Double.MIN_VALUE and 1

setPreferredEdgeLength

public void setPreferredEdgeLength(double preferredEdgeLength)

Sets the preferred edge length. The edges should not become smaller than this amount.

Parameters:

preferredEdgeLength -

setPreferredNodeDistance

public void setPreferredNodeDistance(double preferredNodeDistance)

Sets the preferred node distance.

Parameters:

preferredNodeDistance -

setPreferredEdgeLength

public void setPreferredEdgeLength(Edge edge,
                                   double newEdgeLength)

Sets the preferred edge length for the given edge.

Parameters:

edge -

newEdgeLength -

setInertia

public void setInertia(Node node,
                       double inertia)

Set the inertia for the node. The inertia represents how "easy" a node will move. Inertia "1.0": The node will not move Inertia "0.5": The node will only move half as wide as it would with an inertia of "0.0" Inertia "0.0": The node will move as fast as possible

Parameters:

node -

inertia -

setCenter

public void setCenter(Node node,
                      double x,
                      double y)

Sets the center for the node. This method does not affect the graph itself. Instead the internal data structure of the layouter is changed. This method may be used to update node positions due to user interaction (e.g. dragging).

Parameters:

node -

x -

y -

setRadius

public void setRadius(Node node,
                      double radius)

Sets the radius for the given node

Parameters:

node -

radius -

setStress

public void setStress(Node node,
                      double stress)

Sets the stress for the given node. The higher the stress of a node is, the farther this node will be moved.

Parameters:

node -

stress - a value between 0 and 1

getStress

public double getStress(Node node)

Gets the stress for the given node. The higher the stress of a node is, the farther this node will be moved.

Parameters:

node -

setCenterX

public void setCenterX(Node node,
                       double x)

Sets the center of the node.

Parameters:

node -

x -

setCenterY

public void setCenterY(Node node,
                       double y)

Sets the center of the node.

Parameters:

node -

y -

getCenter

public YPoint getCenter(Node node)

Return the actual center of the node

Parameters:

node -

Returns:

the center of the node or null if the layouter does not know anything about the node.

getCenterX

public double getCenterX(Node node)

Return the actual center of the node.

Parameters:

node -

Returns:

the center of the node.

getCenterY

public double getCenterY(Node node)

Return the actual center of the node.

Parameters:

node -

Returns:

the center of the node.

setMaxTime

public void setMaxTime(long maxTime)

Sets the maximal time the layouter will run. After this time it will sleep - independent of the actual result.

Parameters:

maxTime -

setQuality

public void setQuality(double quality)

Sets the quality ratio (value between 0.0 and 1.0) The higher this value is, the better will be the quality for the resulting layout but also the needed time.

Parameters:

quality - a value between 0 and 1. "1": maximal quality (long running), "0" minimum quality (short running)

getMaxTime

public long getMaxTime()

Return the maximal time the layouter will run (in milliseconds).

Returns:

The maximal time the layouter will run (in milliseconds).

getQuality

public double getQuality()

The quality time ratio set.

Returns:

The quality time ratio set (between 0.0 and 1.0)

syncStructure

public void syncStructure()

This method synchronizes the CopiedLayoutGraph given as parameter to doLayout(y.layout.LayoutGraph) with the original graph. This method

setOutputRestriction

public void setOutputRestriction(OutputRestriction restriction)

Sets a restriction on the output generated by this layouter

Parameters:

restriction - the restriction to use

See Also:

OutputRestriction.NONE, OutputRestriction

getOutputRestriction

public OutputRestriction getOutputRestriction()

Returns the current OutputRestriction instance set for this instance. The default is OutputRestriction.NONE.

Returns:

an OutputRestriction

stopAndWait

public void stopAndWait()

Stops a previously started layout Thread and blocks until the layout is completed.