y.view
Class NodePort

java.lang.Object
  y.view.NodePort

All Implemented Interfaces:

Port

public class NodePort
extends java.lang.Object
implements Port

Graphical representation of a port object (a possible connection point for an edge) associated to a node.

The class provides methods to bind edges to ports, determine connected edges, paint ports, determine port locations, perform hit tests, and store business objects for ports.

Similar to GenericNodeRealizer and GenericEdgeRealizer, this class uses the concept of a configuration that consists of multiple pluggable instances of specialized interfaces to allow for easy customization of its visual appearance.

This class knows multiple nested interfaces that can be used as callback routines to customize

• the rendering of the port (see NodePort.Painter)
• hit tests and edge intersection calculations (see NodePort.ContainsTest and NodePort.IntersectionTest)
• the calculation of the bounding box (see NodePort.UnionRectCalculator and NodePort.BoundsProvider)
• the copying and serialization of arbitrary user-defined data (see NodePort.UserDataHandler)
• the handling of selection state changes of the port (see NodePort.SelectionChangeHandler)

This class provides access to a factory, that is used by the implementation to manage different port style configurations.

Programmers have to use that factory to register different style configurations using their own implementations of the interfaces described above.

The following piece of code demonstrates how to correctly initialize a custom node port.

 // Get the static default factory instance
 NodePort.Factory factory = NodePort.getFactory();

 // Retrieve a map that holds the default NodePort configuration.
 // The implementations contained therein can be replaced one by one in order
 // to create custom configurations...
 Map implementationsMap = factory.createDefaultConfigurationMap();

 // create and register customizations...

 // e.g. create a custom painter
 MyCustomPainter painter = new MyCustomPainter();
 // put it into the map using the interface class as the key
 implementationsMap.put(NodePort.Painter.class, painter);

 // add the configuration using an arbitrary String identifier to the factory
 factory.addConfiguration("type1", implementationsMap);

 // now create an instance that uses our customizations
 NodePort port = new NodePort();
 // initialize the instance using the previously registered configuration
 port.setConfiguration("type1");
 

Note: Serialization/deserialization of node ports is only supported in the GraphML format.

Nested Class Summary

static interface	NodePort.BoundsProvider This interface is used by NodePort to delegate the work of the getBounds() method to.
static interface	NodePort.ContainsTest This interface is used by NodePort to delegate the work of the contains(double, double) method to.
static class	NodePort.Factory This class is used to manage the different configurations for NodePort instances.
static interface	NodePort.IntersectionTest This interface is used by NodePort to delegate the work of the findIntersection(double, double, double, double, java.awt.geom.Point2D) method to.
static interface	NodePort.Painter This interface is used by NodePort to delegate the work of the paint(java.awt.Graphics2D) method to.
static interface	NodePort.SelectionChangeHandler This interface is used by NodePort to notify interested parties of selection state changes.
static interface	NodePort.UnionRectCalculator This interface is used by NodePort to delegate the work of the calcUnionRect(java.awt.geom.Rectangle2D) method to.
static interface	NodePort.UserDataHandler This interface is used by NodePort to delegate the copying of any user-defined data to.

Constructor Summary

NodePort()
Initializes a new NodePort instance.

NodePort(NodePort prototype)
Initializes a new NodePort instance with the values from the specified template instance.

Method Summary

protected void	bindRealizer(NodeRealizer nr) Associates this port instance to the specified node realizer.
void	bindSourcePort(Edge edge) Registers this port instance as connection point at source side for the specified edge.
void	bindSourcePort(EdgeRealizer er) Registers this port instance as connection point at source side for the specified edge.
static void	bindSourcePort(NodePort port, Edge edge) Registers the specified port as connection point at source side for the specified edge.
static void	bindSourcePort(NodePort port, EdgeRealizer er) Registers the specified port as connection point at source side for the specified edge.
void	bindTargetPort(Edge edge) Registers this port instance as connection point at target side for the specified edge.
void	bindTargetPort(EdgeRealizer er) Registers this port instance as connection point at target side for the specified edge.
static void	bindTargetPort(NodePort port, Edge edge) Registers the specified port as connection point at target side for the specified edge.
static void	bindTargetPort(NodePort port, EdgeRealizer er) Registers the specified port as connection point at target side for the specified edge.
void	calcUnionRect(java.awt.geom.Rectangle2D rectangle) Calculates the rectangular union of the specified rectangle and this port's bounds.
boolean	contains(double x, double y) Returns true if this port's visual representation contains the specified point and false otherwise.
NodePort	createCopy() Creates a copy of this port instance that is not associated to any node realizer.
NodePort	createCopy(NodePort prototype) Creates a copy of the specified template instance that is not associated to any node realizer.
EdgeCursor	edges() Returns a cursor over all edges that are bound to this port instance.
boolean	findIntersection(double ix, double iy, double ox, double oy, java.awt.geom.Point2D result) Returns true if the point i=(ix,iy) lies inside and the point o=(ox,oy) lies outside this port's visual representation and false< otherwise.
YRectangle	getBounds() Returns the bounds of this port's visual representation in absolute world (graph) coordinates.
java.lang.String	getConfiguration() Returns the name of the current configuration of this port instance.
static NodePort.Factory	getFactory() Returns the factory instance that will be used to read and write customization configurations.
YPoint	getLocation() Returns the position of this port instance in absolute world coordinates.
PortLocationModelParameter	getModelParameter() Returns the model parameter that determines the position of this port instance.
NodeRealizer	getRealizer() Returns the node realizer instance associated to this port instance.
static NodePort	getSourcePort(Edge edge) Returns the port instance that is registered as the specified edge's source port.
static NodePort	getSourcePort(EdgeRealizer er) Returns the port instance that is registered as the specified edge's source port.
static NodePort	getTargetPort(Edge edge) Returns the port instance that is registered as the specified edge's target port.
static NodePort	getTargetPort(EdgeRealizer er) Returns the port instance that is registered as the specified edge's target port.
java.lang.Object	getUserData() Returns the user or business data associated to this port instance.
EdgeCursor	inEdges() Returns a cursor over all incoming edges that are bound to this port.
boolean	isSelected() Returns the selection state of this port instance.
EdgeCursor	outEdges() Returns a cursor over all outgoing edges that are bound to this port.
void	paint(java.awt.Graphics2D g) Paints this port instance.
static void	remove(NodePort port) Removes the specified node port from its owner realizer as well as all labels that are associated to the port and all edges connecting to it.
void	setConfiguration(java.lang.String id) Configures this instance to use the implementations provided by the factory under the given configuration name.
void	setModelParameter(PortLocationModelParameter parameter) Specifies the model parameter that determines the position of this port instance.
void	setSelected(boolean selected) Specifies the selection state of this port instance.
void	setUserData(java.lang.Object userData) Specifies the user or business data for this port instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

NodePort

public NodePort()

Initializes a new NodePort instance.

NodePort

public NodePort(NodePort prototype)

Initializes a new NodePort instance with the values from the specified template instance.

Parameters:

prototype - the template instance for the new instance's data.

Method Detail

createCopy

public NodePort createCopy()

Creates a copy of this port instance that is not associated to any node realizer. Calls createCopy(this).

Returns:

a copy of this port.

See Also:

createCopy(NodePort)

createCopy

public NodePort createCopy(NodePort prototype)

Creates a copy of the specified template instance that is not associated to any node realizer.

Parameters:

prototype - the template instance for the new instance's data.

Returns:

a copy of the specified port template.

bindRealizer

protected void bindRealizer(NodeRealizer nr)

Associates this port instance to the specified node realizer.

Parameters:

nr - the node realizer to which this port instance has to be bound.

getRealizer

public NodeRealizer getRealizer()

Returns the node realizer instance associated to this port instance.

Returns:

the node realizer instance associated to this port instance or null if this port is not associated to any realizer instance.

bindSourcePort

public void bindSourcePort(Edge edge)

Registers this port instance as connection point at source side for the specified edge. Calls bindSourcePort(y.view.EdgeRealizer).

Parameters:

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Throws:

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

bindSourcePort(NodePort, EdgeRealizer)

bindSourcePort

public void bindSourcePort(EdgeRealizer er)

Registers this port instance as connection point at source side for the specified edge. Calls NodePort.bindSourcePort(this, er).

Parameters:

er - the visual representation of the edge to which the port is bound.

See Also:

bindSourcePort(NodePort, EdgeRealizer)

bindSourcePort

public static void bindSourcePort(NodePort port,
                                  Edge edge)

Registers the specified port as connection point at source side for the specified edge. Registering a port will update the source point of the specified edge's realizer to the port's current position.

Parameters:

port - the port instance to bind as source connection point. May be null.

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Throws:

java.lang.IllegalArgumentException - if the specified port either has no associated NodeRealizer or does not belong to the port collection of its associated NodeRealizer.

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

getSourcePort(EdgeRealizer)

bindSourcePort

public static void bindSourcePort(NodePort port,
                                  EdgeRealizer er)

Registers the specified port as connection point at source side for the specified edge. Registering a port will update the specified realizer's source point to the port's current position.

Parameters:

port - the port instance to bind as source connection point. May be null.

er - the visual representation of the edge to which the port is bound.

Throws:

java.lang.IllegalArgumentException - if the specified port either has no associated NodeRealizer or does not belong to the port collection of its associated NodeRealizer.

See Also:

getSourcePort(EdgeRealizer)

getSourcePort

public static NodePort getSourcePort(Edge edge)

Returns the port instance that is registered as the specified edge's source port.

Parameters:

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Returns:

the port instance that is registered as the specified edge's source port or null if the edge is not bound to a source port.

Throws:

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

bindSourcePort(NodePort, EdgeRealizer)

getSourcePort

public static NodePort getSourcePort(EdgeRealizer er)

Returns the port instance that is registered as the specified edge's source port.

Parameters:

er - the visual representation of the edge to which the port is bound.

Returns:

the port instance that is registered as the specified edge's source port or null if the edge is not bound to a source port.

See Also:

bindSourcePort(NodePort, EdgeRealizer)

bindTargetPort

public void bindTargetPort(Edge edge)

Registers this port instance as connection point at target side for the specified edge. Calls bindTargetPort(y.view.EdgeRealizer).

Parameters:

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Throws:

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

bindTargetPort(NodePort, EdgeRealizer)

bindTargetPort

public void bindTargetPort(EdgeRealizer er)

Registers this port instance as connection point at target side for the specified edge. Calls NodePort.bindTargetPort(this, er).

Parameters:

er - the visual representation of the edge to which the port is bound.

See Also:

bindTargetPort(NodePort, EdgeRealizer)

bindTargetPort

public static void bindTargetPort(NodePort port,
                                  Edge edge)

Registers the specified port as connection point at target side for the specified edge. Registering a port will update the target point of the specified edge's realizer to the port's current position.

Parameters:

port - the port instance to bind as target connection point. May be null.

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Throws:

java.lang.IllegalArgumentException - if the specified port either has no associated NodeRealizer or does not belong to the port collection of its associated NodeRealizer.

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

getTargetPort(EdgeRealizer)

bindTargetPort

public static void bindTargetPort(NodePort port,
                                  EdgeRealizer er)

Registers the specified port as connection point at target side for the specified edge. Registering a port will update the specified realizer's target point to the port's current position.

Parameters:

port - the port instance to bind as target connection point. May be null.

er - the visual representation of the edge to which the port is bound.

Throws:

java.lang.IllegalArgumentException - if the specified port either has no associated NodeRealizer or does not belong to the port collection of its associated NodeRealizer.

See Also:

getTargetPort(EdgeRealizer)

getTargetPort

public static NodePort getTargetPort(Edge edge)

Returns the port instance that is registered as the specified edge's target port.

Parameters:

edge - the edge to which the port is bound. Must belong to a Graph2D instance.

Returns:

the port instance that is registered as the specified edge's target port or null if the edge is not bound to a target port.

Throws:

java.lang.NullPointerException - if the specified edge does not belong to a graph.

See Also:

bindTargetPort(NodePort, EdgeRealizer)

getTargetPort

public static NodePort getTargetPort(EdgeRealizer er)

Returns the port instance that is registered as the specified edge's target port.

Parameters:

er - the visual representation of the edge to which the port is bound.

Returns:

the port instance that is registered as the specified edge's target port or null if the edge is not bound to a target port.

See Also:

bindTargetPort(NodePort, EdgeRealizer)

edges

public EdgeCursor edges()

Returns a cursor over all edges that are bound to this port instance. I.e. for all edges the associated EdgeRealizer instance satisfies

NodePort.getSourcePort(realizer) == this || NodePort.getTargetPort(realizer) == this

If this port is not bound to any node or the associated node does not belong to any graph, the cursor will be empty.

Returns:

a cursor for for edges that are bound to this port.

inEdges

public EdgeCursor inEdges()

Returns a cursor over all incoming edges that are bound to this port. I.e. for all edges the associated EdgeRealizer instance satisfies

NodePort.getTargetPort(realizer) == this

If this port is not bound to any node or the associated node does not belong to any graph, the cursor will be empty.

Returns:

a cursor for incoming edges that are bound to this port.

outEdges

public EdgeCursor outEdges()

Returns a cursor over all outgoing edges that are bound to this port. I.e. for all edges the associated EdgeRealizer instance satisfies

NodePort.getSourcePort(realizer) == this

If this port is not bound to any node or the associated node does not belong to any graph, the cursor will be empty.

Returns:

a cursor for outgoing edges that are bound to this port.

remove

public static void remove(NodePort port)

Removes the specified node port from its owner realizer as well as all labels that are associated to the port and all edges connecting to it.

Parameters:

port - the port instance to be removed.

See Also:

PortLabelModel.findLabels(NodePort), edges()

isSelected

public boolean isSelected()

Returns the selection state of this port instance.

Returns:

the selection state of this port instance.

See Also:

setSelected(boolean)

setSelected

public void setSelected(boolean selected)

Specifies the selection state of this port instance.

Parameters:

selected - the new selection state of this port instance.

See Also:

isSelected(), NodePort.SelectionChangeHandler

getModelParameter

public PortLocationModelParameter getModelParameter()

Returns the model parameter that determines the position of this port instance.

Returns:

the model parameter that determines the position of this port instance.

See Also:

setModelParameter(PortLocationModelParameter)

setModelParameter

public void setModelParameter(PortLocationModelParameter parameter)

Specifies the model parameter that determines the position of this port instance.

Parameters:

parameter - the new model parameter.

See Also:

getModelParameter()

getLocation

public YPoint getLocation()

Returns the position of this port instance in absolute world coordinates.

Returns:

the position of this port instance in absolute world coordinates.

getUserData

public java.lang.Object getUserData()

Returns the user or business data associated to this port instance.

Returns:

the user or business data associated to this port instance

See Also:

setUserData(Object), NodePort.UserDataHandler

setUserData

public void setUserData(java.lang.Object userData)

Specifies the user or business data for this port instance.

Parameters:

userData - the new user or business data for this port instance.

See Also:

getUserData(), NodePort.UserDataHandler

getConfiguration

public java.lang.String getConfiguration()

Returns the name of the current configuration of this port instance.

Returns:

the name of the current configuration of this port instance.

See Also:

setConfiguration(String)

setConfiguration

public void setConfiguration(java.lang.String id)

Configures this instance to use the implementations provided by the factory under the given configuration name.

Parameters:

id - The name of the configuration to use. The specified name must have been registered with the factory prior to the invocation of this method.

See Also:

getConfiguration()

getFactory

public static NodePort.Factory getFactory()

Returns the factory instance that will be used to read and write customization configurations.

Returns:

the factory instance that will be used to read and write customization configurations.

contains

public boolean contains(double x,
                        double y)

Returns true if this port's visual representation contains the specified point and false otherwise. The check is delegated to the NodePort.ContainsTest implementation that is registered for this port's configuration. If no such implementation is registered, ShapePortConfiguration.contains(NodePort, double, double) is used instead.

Parameters:

x - the x-coordinate of the point to check.

y - the y-coordinate of the point to check.

Returns:

true if this port's visual representation contains the specified point and false otherwise.

findIntersection

public boolean findIntersection(double ix,
                                double iy,
                                double ox,
                                double oy,
                                java.awt.geom.Point2D result)

Returns true if the point i=(ix,iy) lies inside and the point o=(ox,oy) lies outside this port's visual representation and false< otherwise. If i lies inside and o lies outside, then the intersection of the line segment through i and o and the boundary of this port's visual representation is stored in the result parameter. The calculation is delegated to the NodePort.IntersectionTest implementation that is registered for this port's configuration. If no such implementation is registered, ShapePortConfiguration.findIntersection(NodePort, double, double, double, double, java.awt.geom.Point2D) is used instead.

Parameters:

ix - the x-coordinate of the point that has to lie inside the port's visual representation.

iy - the y-coordinate of the point that has to lie inside the port's visual representation.

ox - the x-coordinate of the point that has to lie outside the port's visual representation.

oy - the y-coordinate of the point that has to lie outside the port's visual representation.

result - an output parameter to store the intersection of the line segment through i and o and the port's visual representation. If this method returns false, the value of this parameter is undefined.

Returns:

true if (ix,iy) lies inside and (ox,oy) lies outside this port's visual representation and false< otherwise.

paint

public void paint(java.awt.Graphics2D g)

Paints this port instance. The painting is delegated to the NodePort.Painter implementation that is registered for this port's configuration. If no such implementation is registered, ShapePortConfiguration.paint(NodePort, java.awt.Graphics2D) is used instead.

Parameters:

g - the graphics context to paint upon.

getBounds

public YRectangle getBounds()

Returns the bounds of this port's visual representation in absolute world (graph) coordinates. This method queries the NodePort.BoundsProvider implementation that is registered for this port's configuration. If no such implementation is registered, ShapePortConfiguration.getBounds(NodePort) is queried instead.

Returns:

the bounds of this port's visual representation.

calcUnionRect

public void calcUnionRect(java.awt.geom.Rectangle2D rectangle)

Calculates the rectangular union of the specified rectangle and this port's bounds. The calculation is delegated to the NodePort.UnionRectCalculator implementation is registered for this port's configuration. If no such implementation is registered, ShapePortConfiguration.calcUnionRect(NodePort, java.awt.geom.Rectangle2D) is used instead.

Parameters:

rectangle - the rectangle to be enlarged such that it contains the bounds of this port instance.