edu.uci.ics.jung.visualization
Class AbstractLayout

java.lang.Object
  extended by edu.uci.ics.jung.visualization.AbstractLayout
All Implemented Interfaces:
ChangeEventSupport, Layout, VertexLocationFunction
Direct Known Subclasses:
CircleLayout, FastScalableMDS, FRLayout, ISOMLayout, KKLayout, KKLayoutInt, SpringLayout, StaticLayout, TreeLayout

public abstract class AbstractLayout
extends Object
implements Layout, ChangeEventSupport

Implements some of the dirty work of writing a layout algorithm, allowing the user to express their major intent more simply. When writing a Layout, there are many shared tasks: handling tracking locked nodes, applying filters, and tracing nearby vertices. This package automates all of those.

Author:
Danyel Fisher, Scott White

Field Summary
protected  ChangeEventSupport changeSupport
           
protected  VertexLocationFunction vertex_locations
           
 
Constructor Summary
AbstractLayout(Graph g)
          Constructor.
 
Method Summary
 void addChangeListener(ChangeListener l)
          Adds a ChangeListener.
abstract  void advancePositions()
          Implementors must override this method in order to create a Layout.
 void applyFilter(Graph g)
          Applies the filter to the current graph.
 boolean dontMove(Vertex v)
          Deprecated. As of version 1.7.5, superseded by Layout.isLocked(Vertex).
 void fireStateChanged()
          Notifies all listeners that have registered interest for notification on this event type.
 void forceMove(Vertex picked, double x, double y)
          Forcibly moves a vertex to the (x,y) location by setting its x and y locations to the inputted location.
protected  Vertex getAVertex(Edge e)
          Utility method, gets a single vertex from this edge.
 Object getBaseKey()
          Returns a visualization-specific key (that is, specific both to this instance and AbstractLayout) that can be used to access UserData related to the AbstractLayout.
 ChangeListener[] getChangeListeners()
          Returns an array of all the ChangeListeners added with addChangeListener().
 Coordinates getCoordinates(ArchetypeVertex v)
          Returns the Coordinates object that stores the vertex' x and y location.
 Dimension getCurrentSize()
          Returns the current size of the visualization space, accoring to the last call to resize().
 Edge getEdge(double x, double y)
          Deprecated. Use PickSupport instead
 Edge getEdge(double x, double y, double maxDistance)
          Deprecated. Use PickSupport instead
 Graph getGraph()
          Accessor for the graph that represets all vertices.
 Point2D getLocation(ArchetypeVertex v)
           
 String getStatus()
          Returns the current status of the sytem, or null if there is no particular status to report.
 Vertex getVertex(double x, double y)
          Deprecated. Use PickSupport instead
 Vertex getVertex(double x, double y, double maxDistance)
          Deprecated. Use PickSupport instead
 Iterator getVertexIterator()
           
 Set getVisibleEdges()
          Returns the set of edges from the original getGraph that are now visible.
protected  Graph getVisibleGraph()
          Accessor for the graph that represets all visible vertices.
 Set getVisibleVertices()
          Returns the set of vertices from the original getGraph that are now visible.
 double getX(Vertex v)
          Returns the x coordinate of the vertex from the Coordinates object.
 double getY(Vertex v)
          Returns the y coordinate of the vertex from the Coordinates object.
protected abstract  void initialize_local_vertex(Vertex v)
          Initializes the local information on a single vertex.
protected  void initialize_local()
          Initializes all local information, and is called immediately within the initialize() process.
 void initialize(Dimension size)
          Initializer, calls intialize_local and initializeLocations to start construction process.
 void initialize(Dimension size, VertexLocationFunction v_locations)
           
protected  void initializeLocation(Vertex v, Coordinates coord, Dimension d)
          Sets random locations for a vertex within the dimensions of the space.
protected  void initializeLocations()
          This method calls initialize_local_vertex for each vertex, and also adds initial coordinate information for each vertex.
 boolean isLocked(Vertex v)
          Returns true if the position of vertex v is locked.
 void lockVertex(Vertex v)
          Adds the vertex to the DontMove list
protected  void offsetVertex(Vertex v, double xOffset, double yOffset)
           
protected  void postInitialize()
          may be overridden to do something after initializeLocations call
 void removeChangeListener(ChangeListener l)
          Removes a ChangeListener.
 void resize(Dimension size)
          When a visualization is resized, it presumably wants to fix the locations of the vertices and possibly to reinitialize its data.
 void restart()
          Resets the vertex positions to their initial locations.
 void unlockVertex(Vertex v)
          Removes the vertex from the DontMove list
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface edu.uci.ics.jung.visualization.Layout
incrementsAreDone, isIncremental
 

Field Detail

changeSupport

protected ChangeEventSupport changeSupport

vertex_locations

protected VertexLocationFunction vertex_locations
Constructor Detail

AbstractLayout

public AbstractLayout(Graph g)
Constructor. Initializes the current size to be 100x100, both the graph and the showing graph to the argument, and creates the dontmove set.

Parameters:
g -
Method Detail

dontMove

public boolean dontMove(Vertex v)
Deprecated. As of version 1.7.5, superseded by Layout.isLocked(Vertex).

The set of vertices that have been locked. When running layout, it is important to check
  if (dontmove( v )) { ... }
 

Returns:
whether this vertex may be legally moved or not

isLocked

public boolean isLocked(Vertex v)
Description copied from interface: Layout
Returns true if the position of vertex v is locked.

Specified by:
isLocked in interface Layout
See Also:
Layout.lockVertex(Vertex), Layout.unlockVertex(Vertex)

getVertexIterator

public Iterator getVertexIterator()
Specified by:
getVertexIterator in interface VertexLocationFunction

initialize

public void initialize(Dimension size)
Initializer, calls intialize_local and initializeLocations to start construction process.

Specified by:
initialize in interface Layout

initialize

public void initialize(Dimension size,
                       VertexLocationFunction v_locations)

initialize_local

protected void initialize_local()
Initializes all local information, and is called immediately within the initialize() process. The user is responsible for overriding this method to do any construction that may be necessary: for example, to initialize local per-edge or graph-wide data.


postInitialize

protected void postInitialize()
may be overridden to do something after initializeLocations call


initialize_local_vertex

protected abstract void initialize_local_vertex(Vertex v)
Initializes the local information on a single vertex. The user is responsible for overriding this method to do any vertex-level construction that may be necessary: for example, to attach vertex-level information to each vertex.


getBaseKey

public Object getBaseKey()
Returns a visualization-specific key (that is, specific both to this instance and AbstractLayout) that can be used to access UserData related to the AbstractLayout.


initializeLocations

protected void initializeLocations()
This method calls initialize_local_vertex for each vertex, and also adds initial coordinate information for each vertex. (The vertex's initial location is set by calling initializeLocation.


initializeLocation

protected void initializeLocation(Vertex v,
                                  Coordinates coord,
                                  Dimension d)
Sets random locations for a vertex within the dimensions of the space. If you want to initialize in some different way, override this method.

Parameters:
coord -
d -

getStatus

public String getStatus()
Returns the current status of the sytem, or null if there is no particular status to report. Useful for reporting things like number of iterations passed, temperature, and so on.By default, an AbstractLayout returns null for its status.

Specified by:
getStatus in interface Layout
Returns:
the status, as a string

advancePositions

public abstract void advancePositions()
Implementors must override this method in order to create a Layout. If the Layout is the sort that only calculates locations once, this method may be overridden with an empty method.

Note that "locked" vertices are not to be moved; however, it is the policy of the visualization to decide how to handle them, and what to do with the vertices around them. Prototypical code might include a clipping like

  for (Iterator i = getVertices().iterator(); i.hasNext() ) { Vertex v = (Vertex) i.next(); if (! dontmove.contains( v ) ) { ... // handle the node } else { // ignore the node } }
 

Specified by:
advancePositions in interface Layout
See Also:
Layout.advancePositions()

getVisibleGraph

protected Graph getVisibleGraph()
Accessor for the graph that represets all visible vertices. Warning: This graph consists of vertices that are equivalent to, but are not the same as the vertices in getGraph(), nor the vertices in getAllVertices(). Rather, it returns the vertices and edges that were passed in during a call to applyFilter. The call getVisibleGraph().getVertices(), is almost indubitably incorrect.

Returns:
the current visible graph.
See Also:
getVisibleEdges(), getVisibleVertices()

getCurrentSize

public Dimension getCurrentSize()
Returns the current size of the visualization space, accoring to the last call to resize().

Specified by:
getCurrentSize in interface Layout
Returns:
the current size of the screen

getAVertex

protected Vertex getAVertex(Edge e)
Utility method, gets a single vertex from this edge. The utility's implementation is to get the iterator from the edge's getIncidentVertices() and then return the first element.


getCoordinates

public Coordinates getCoordinates(ArchetypeVertex v)
Returns the Coordinates object that stores the vertex' x and y location.

Parameters:
v - A Vertex that is a part of the Graph being visualized.
Returns:
A Coordinates object with x and y locations.

getX

public double getX(Vertex v)
Returns the x coordinate of the vertex from the Coordinates object. in most cases you will be better off calling getLocation(Vertex v);

Specified by:
getX in interface Layout
Parameters:
v - The vertex being examined
Returns:
the x coordinate of that vertex
See Also:
Layout.getX(edu.uci.ics.jung.graph.Vertex)

getY

public double getY(Vertex v)
Returns the y coordinate of the vertex from the Coordinates object. In most cases you will be better off calling getLocation(Vertex v)

Specified by:
getY in interface Layout
Parameters:
v - The vertex being examined
Returns:
the y coordinate of that vertex
See Also:
Layout.getX(edu.uci.ics.jung.graph.Vertex)

getLocation

public Point2D getLocation(ArchetypeVertex v)
Specified by:
getLocation in interface Layout
Specified by:
getLocation in interface VertexLocationFunction
Parameters:
v - a Vertex of interest
Returns:
the location point of the supplied vertex

resize

public void resize(Dimension size)
When a visualization is resized, it presumably wants to fix the locations of the vertices and possibly to reinitialize its data. The current method calls initializeLocations followed by initialize_local. TODO: A better implementation wouldn't destroy the current information, but would either scale the current visualization, or move the nodes toward the new center.

Specified by:
resize in interface Layout

offsetVertex

protected void offsetVertex(Vertex v,
                            double xOffset,
                            double yOffset)
Parameters:
v -
xOffset -
yOffset -

restart

public void restart()
Description copied from interface: Layout
Resets the vertex positions to their initial locations.

Specified by:
restart in interface Layout
See Also:
Layout.restart()

getVertex

public Vertex getVertex(double x,
                        double y)
Deprecated. Use PickSupport instead

Gets the vertex nearest to the location of the (x,y) location selected. Calls the longer form of the call.

Specified by:
getVertex in interface Layout
Parameters:
x - The x coordinate of the input
y - The y coordinate of the input
Returns:
The nearest vertex. It is up to the user to check if it is satisfactorily close.

getVertex

public Vertex getVertex(double x,
                        double y,
                        double maxDistance)
Deprecated. Use PickSupport instead

Gets the vertex nearest to the location of the (x,y) location selected, within a distance of maxDistance. Iterates through all visible vertices and checks their distance from the click. Override this method to provde a more efficient implementation.

Specified by:
getVertex in interface Layout
Parameters:
x - The x coordinate of the input
y - The y coordinate of the input
maxDistance - The maximum acceptable distance. Beyond this, vertices are ignored.
Returns:
The nearest vertex. It is up to the user to check if it is satisfactorily close.

getEdge

public Edge getEdge(double x,
                    double y)
Deprecated. Use PickSupport instead

Gets the edge nearest to the location of the (x,y) location selected. Calls the longer form of the call.


getEdge

public Edge getEdge(double x,
                    double y,
                    double maxDistance)
Deprecated. Use PickSupport instead

Gets the edge nearest to the location of the (x,y) location selected, within a distance of maxDistance, Iterates through all visible edges and checks their distance from the click. Override this method to provide a more efficient implementation.

Parameters:
x -
y -
maxDistance -
Returns:
Edge closest to the click.

getGraph

public Graph getGraph()
Accessor for the graph that represets all vertices.

Specified by:
getGraph in interface Layout
Returns:
the graph that contains all vertices.

getVisibleEdges

public Set getVisibleEdges()
Returns the set of edges from the original getGraph that are now visible. These edges are equivalent to the ones passed in from the Graph argument to applyFilter().

Specified by:
getVisibleEdges in interface Layout

getVisibleVertices

public Set getVisibleVertices()
Returns the set of vertices from the original getGraph that are now visible. These vertices are equivalent to the ones passed in from the Graph argument to applyFilter().

Specified by:
getVisibleVertices in interface Layout

forceMove

public void forceMove(Vertex picked,
                      double x,
                      double y)
Forcibly moves a vertex to the (x,y) location by setting its x and y locations to the inputted location. Does not add the vertex to the "dontmove" list, and (in the default implementation) does not make any adjustments to the rest of the graph.

Specified by:
forceMove in interface Layout

lockVertex

public void lockVertex(Vertex v)
Adds the vertex to the DontMove list

Specified by:
lockVertex in interface Layout
Parameters:
v - vertex
See Also:
Layout.unlockVertex(Vertex), Layout.isLocked(Vertex)

unlockVertex

public void unlockVertex(Vertex v)
Removes the vertex from the DontMove list

Specified by:
unlockVertex in interface Layout
Parameters:
v - vertex
See Also:
Layout.lockVertex(Vertex), Layout.isLocked(Vertex)

applyFilter

public void applyFilter(Graph g)
Applies the filter to the current graph. The default implementation merely makes fewer vertices available to the getVisibleVertices and getVisibleEdges methods.

Specified by:
applyFilter in interface Layout
Parameters:
g - a filtered graph that is a subgraph of the Graph returned by getGraph
See Also:
Layout.applyFilter(Graph g)

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener.

Specified by:
addChangeListener in interface ChangeEventSupport
Parameters:
l - the listener to be added

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener.

Specified by:
removeChangeListener in interface ChangeEventSupport
Parameters:
l - the listener to be removed

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added with addChangeListener().

Specified by:
getChangeListeners in interface ChangeEventSupport
Returns:
all of the ChangeListeners added or an empty array if no listeners have been added

fireStateChanged

public void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created. The primary listeners will be views that need to be repainted because of changes in this model instance

Specified by:
fireStateChanged in interface ChangeEventSupport
See Also:
EventListenerList