edu.uci.ics.jung.visualization
Class AbstractLayout

java.lang.Object
  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.By default, an AbstractLayout returns null for its status.
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