com.nwoods.jgo
Class JGoPort

java.lang.Object
  extended bycom.nwoods.jgo.JGoObject
      extended bycom.nwoods.jgo.JGoDrawable
          extended bycom.nwoods.jgo.JGoPort
All Implemented Interfaces:
JGoIdentifiablePart, JGoXMLSaveRestore, java.io.Serializable

public class JGoPort
extends JGoDrawable
implements JGoIdentifiablePart

A connection point for JGoLink objects. Each port has a collection of JGoLinks that are attached to the port.

By default a JGoPort appears as a circle, but it can use any other JGoObject to control its appearance. The predefined styles are:

For your application, some ports may be valid sources for links, some may be valid destinations, and some may be both or neither. It may be that some particular pairs of ports cannot have a valid new link between them. (For example, you may want to avoid having two different links connecting the same two ports.) JGoView calls the isValidSource(), isValidDestination() and validLink() methods to allow the particular port classes the ability to control whether the user can draw a link starting at a given port and ending at one.

Links that are connected to a port may be constrained to come into the port or come out of the port from certain directions, as specified by the JGoObject Spot locations. Use NoSpot to indicate that any direction is acceptable. (The old PortSide... constants have been replaced by the Spot location constants; for example, PortSideLeft is now JGoObject.LeftCenter.) The getLinkDir() method is responsible for determining the direction in radians that links will connect with the port.

Because ports have a size, the exact point at which a link should terminate may want to depend on the dimensions of the port. The getLinkPoint() method is responsible for calculating this Point. Override this method to produce more sophisticated link appearances. Usually if the link direction for the port is on one side, the link point will be on the same side to avoid overlapping the link with the visual appearance of the port.

If the style is StyleObject, the JGoObject representing the port is called a PortObject. It can be any JGoObject except a JGoControl. It is automatically resized and repositioned to match the port whenever it is painted. Although the JGoPort is normally part of a document, the PortObject must not be part of a document or a view. These PortObjects can be shared by many JGoPorts; they are not copied by JGoPort.copyObject(), and are not removed from any document when the JGoPort is removed from a document. This optimization will allow many different ports to use a single instance of a JGoImage, for example.

Often you will have several objects used by ports, say of different images, each accessible in a different static variable. To change the appearance of a port you just need to call setPortObject() with the appropriate object.

Note that if you make a change to a PortObject, rather than changing the JGoPort's properties, any ports that use that object will not have their apperance updated until they are repainted. You may need to call update all views of all documents that have ports using that object.

Use the following methods to iterate over a port's collection of links:

Because JGoPort is a subclass of JGoDrawable (instead of JGoObject), you can control the pen and brush characteristics of ports that aren't of StyleObject or StyleHidden just by calling setPen() and/or setBrush().

There is support for greeking, to speed up painting at small view scales. The paintGreek method is called by the paint method, and gets the opportunity to change the rendering method used depending on the view's scale. Two new static properties have been added to control the default greeking behavior.

See Also:
Serialized Form

Field Summary
static int ChangedAddedLink
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: added a link
static int ChangedEndSegmentLength
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed length of a link's end segment at this port
static int ChangedFromSpot
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the link spot for links going from this port has changed
static int ChangedObject
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port object has changed
static int ChangedPartID
          a CHANGED JGoDocumentEvent or JGoViewEvent hint:
static int ChangedRemovedLink
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: removed a link
static int ChangedStyle
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port style has changed
static int ChangedToSpot
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the link spot for links going to this port has changed
static int ChangedValidDestination
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port's ability to act as a destination for links (a link's "to" port) has changed
static int ChangedValidDuplicateLinks
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed the ValidDuplicateLinks property
static int ChangedValidSelfNode
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed the ValidSelfNode property
static int ChangedValidSource
          a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port's ability to act as a source for links (a link's "from" port) has changed
static int StyleDiamond
          The port will be drawn as a diamond
static int StyleEllipse
          The port will be drawn as an ellipse
static int StyleHidden
          The port will have no predefined visual representation
static int StyleObject
          The port will be shown with a JGo object
static int StyleRectangle
          The port will be drawn as a rectangle
static int StyleTriangle
          The port will be drawn as a triangle
 
Fields inherited from class com.nwoods.jgo.JGoObject
Bottom, BottomCenter, BottomLeft, BottomMiddle, BottomRight, Center, CenterLeft, CenterRight, Changed4ResizeHandles, ChangedAutoRescale, ChangedBrush, ChangedDraggable, ChangedDragsNode, ChangedGeometry, ChangedGrabChildSelection, ChangedInitializing, ChangedPen, ChangedResizable, ChangedSelectable, ChangedUpdatePartner, ChangedVisible, ChangedZOrder, LastChangedHint, Left, LeftCenter, NoHandle, NoSpot, NumReservedHandles, RepaintAll, Right, RightCenter, SideLeft, SideRight, Top, TopCenter, TopLeft, TopMiddle, TopRight
 
Constructor Summary
JGoPort()
          Create a new port shown as an ellipse.
JGoPort(org.eclipse.swt.graphics.Point location, Dimension size)
          Construct a port at the given location with the given size.
JGoPort(org.eclipse.swt.graphics.Rectangle rect)
          Create a new port with the given bounding rectangle.
JGoPort(org.eclipse.swt.graphics.Rectangle rect, JGoObject object)
          Create a new port with the given bounding rectangle.
 
Method Summary
 boolean canLinkFrom()
          This predicate should be true if, by itself, there is no known reason why one couldn't create a valid link from this port to some port.
 boolean canLinkTo()
          This predicate should be true if, by itself, there is no known reason why one couldn't create a valid link from some port to this one.
 void changeValue(JGoDocumentChangedEdit e, boolean undo)
          This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the property value change for a JGoObject.
 void copyNewValueForRedo(JGoDocumentChangedEdit e)
          This method is called when a JGoDocumentChangedEdit is created for a JGoDocumentEvent.CHANGED event, when a JGoObject has been changed.
 JGoObject copyObject(JGoCopyEnvironment env)
          Create a new instance of this object.
 void copyObjectDelayed(JGoCopyEnvironment env, JGoObject newobj)
          For objects that require a second pass to complete the copying, this method is called after the first pass of copying all of the objects in JGoDocument.copyFromCollection.
 boolean doUncapturedMouseMove(int flags, org.eclipse.swt.graphics.Point dc, org.eclipse.swt.graphics.Point vc, JGoView view)
          Called when the mouse moves over this port --- we set the current cursor to be a Hand if the user can start drawing a new link at this port.
 void expandRectByPenWidth(org.eclipse.swt.graphics.Rectangle rect)
          Modify the given rectangle to account for any likely drawing beyond the bounds of the rectangle caused by wide pens.
protected  void geometryChange(org.eclipse.swt.graphics.Rectangle prevRect)
          Called just after the bounding rectangle for this object has been changed.
static double getDefaultPaintGreekScale()
          Return the view scale at which this text object should paint something simpler than real text.
static double getDefaultPaintNothingScale()
          Return the view scale at which a text object should not paint anything.
 int getEndSegmentLength()
          Return how long a line to draw straight out from the port before "turning" (assuming non-orthogonal routing and a non-Center direction for links).
 JGoListPosition getFirstLinkPos()
          Return the position of the first link in the collection of links connected to this port.
 double getFromLinkDir()
          Return the direction in radians of the first segment of links coming from this port.
 double getFromLinkDir(JGoLink link)
          Determine the direction, in radians, that a link will go when coming out of this port.
 org.eclipse.swt.graphics.Point getFromLinkPoint()
          Return the point where links whose source is this port should connect to this port.
 org.eclipse.swt.graphics.Point getFromLinkPoint(JGoLink link, org.eclipse.swt.graphics.Point result)
          Return the point where the given outgoing link should connect to this port.
 org.eclipse.swt.graphics.Point getFromLinkPoint(org.eclipse.swt.graphics.Point result)
          Return the point where links whose source is this port should connect to this port.
 int getFromSpot()
          Return the spot of the port at which to connect links coming from this port.
 JGoLink getLinkAtPos(JGoListPosition pos)
          Return the link at the specified position in the collection of links connected to this port.
 double getLinkDir(int spot)
          Given a spot, return the direction in radians of the first segment of the link.
 org.eclipse.swt.graphics.Point getLinkPoint(int spot)
          Given a particular spot, return where the link should connect up to on this port.
 org.eclipse.swt.graphics.Point getLinkPoint(int spot, org.eclipse.swt.graphics.Point result)
          Given a particular spot, return where the link should connect up to on this port.
 org.eclipse.swt.graphics.Point getLinkPointFromPoint(int x, int y, org.eclipse.swt.graphics.Point result)
          Return the point where a link coming from the given point should connect.
 boolean getNearestIntersectionPoint(int px, int py, int cx, int cy, org.eclipse.swt.graphics.Point result)
          Consider the pen width in determining the nearest intersection point.
 JGoListPosition getNextLinkPos(JGoListPosition pos)
          Return the position of the next link in the collection of links connected to this port.
 int getNumFromLinks()
          Returns the number of links coming from this port.
 int getNumLinks()
          Returns the number of links currently attached to this port.
 int getNumToLinks()
          Returns the number of links coming to this port.
 int getPartID()
          Return the integer PartID for this JGoObject that is in a JGoDocument.
 JGoObject getPortObject()
          Returns the current PortObject.
 int getStyle()
          Returns the current style of the port.
 double getToLinkDir()
          Return the direction in radians of the first segment of links going to this port.
 double getToLinkDir(JGoLink link)
          Determine the direction, in radians, that a link will go when going into this port.
 org.eclipse.swt.graphics.Point getToLinkPoint()
          Return the point where links whose destination is this port should connect to this port.
 org.eclipse.swt.graphics.Point getToLinkPoint(JGoLink link, org.eclipse.swt.graphics.Point result)
          Return the point where the given incoming link should connect to this port.
 org.eclipse.swt.graphics.Point getToLinkPoint(org.eclipse.swt.graphics.Point result)
          Return the point where links whose destination is this port should connect to this port.
 int getToSpot()
          Return the spot of the port at which to connect links going to this port.
 boolean hasNoLinks()
          This predicate indicates whether there are any links attached to this port.
 boolean isInSameNode(JGoPort p)
          Determine whether this port is in the "same" node as another port.
static boolean isInSameNode(JGoPort a, JGoPort b)
          This static method determines if both ports belong to the same node.
 boolean isLinked(JGoPort p)
          Determine whether there is already a link from this port to another port.
static boolean isLinked(JGoPort a, JGoPort b)
          This static method determines if there is a link going from one port to another.
 boolean isValidDestination()
          Return whether or not a link can end at this port, as the potential "to" port for a link.
 boolean isValidDuplicateLinks()
          Return whether a valid link can be made between two ports already connected by a link.
 boolean isValidLink()
          This predicate is true when JGoView.validLink() returned true between the originating port and this port.
 boolean isValidSelfNode()
          Returns whether a valid link can be made between two ports belonging to the same node.
 boolean isValidSource()
          Return whether or not a link can start at this port, as the potential "from" port for a link.
 void linkChange()
          Called whenever a link has been added or removed from this port.
protected  void ownerChange(JGoObjectCollection oldOwner, JGoObjectCollection newOwner, JGoObject mainObject)
          Called whenever this object's owner (JGoView or JGoDocument) changes.
 void paint(Graphics2D g, JGoView view)
          Draws the port depending on what style it is.
 boolean paintGreek(Graphics2D g, JGoView view)
          This method is called by paint to allow optimizing drawing a lot of objects at small scales.
 void portChange(int hint, int prevInt, java.lang.Object prevVal)
          Called whenever any change happens to a port that may require the links connected to this port to be modified (move, resize, etc).
 void removeAllLinks()
          This convenience method unlinks all links attached to this port.
static void setDefaultPaintGreekScale(double s)
          Change the scale at which text will paint very simply.
static void setDefaultPaintNothingScale(double s)
          Change the scale at which text will not paint.
 void setEndSegmentLength(int len)
          Set how long a straight segment there should be for links at this port if the spot is not NoSpot.
 void setFromSpot(int spot)
          Set which spot of the port is to be used to connect links coming from this port.
 void setPartID(int id)
          Change the PartID for a JGoObject; this is normally only called by JGoDocument code when this object is added to a document layer.
 void setPortObject(JGoObject obj)
          Sets the current PortObject.
 void setStyle(int s)
          Sets the current style of the port.
 void setToSpot(int spot)
          Set which spot of the port is to be used to connect links going to this port.
 void setValidDestination(boolean valid)
          Set whether the user can draw a link with this port as the "to" end of the link.
 void setValidDuplicateLinks(boolean valid)
          Change whether duplicate links to another port may be valid at this port.
 void setValidSelfNode(boolean valid)
          Change whether a link may be valid to another port that is part of the same node as this port.
 void setValidSource(boolean valid)
          Set whether the user can draw a link with this port as the "from" end of the link.
 DomNode SVGReadObject(DomDoc svgDoc, JGoDocument jGoDoc, DomElement svgElement, DomElement jGoChildElement)
          Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void SVGUpdateReference(java.lang.String attr, java.lang.Object referencedObject)
          This method will be called to fill in object references.
 void SVGWriteObject(DomDoc svgDoc, DomElement jGoElementGroup)
          Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 boolean validLink(JGoPort to)
          Return whether or not a link from this port to "to" is valid.
 
Methods inherited from class com.nwoods.jgo.JGoDrawable
draw3DRect, draw3DRect, drawEllipse, drawEllipse, drawEllipse, drawLine, drawLine, drawPath, drawPolygon, drawPolygon, drawRect, drawRect, drawRect, drawRoundRect, drawRoundRect, getBrush, getPen, setBrush, setPen, SVGAddPathArgs, SVGReadAttributes, SVGWriteAttributes
 
Methods inherited from class com.nwoods.jgo.JGoObject
canView, computeBoundingRect, computeMove, computeResize, copy, copyOldValueForUndo, copyRect, doMouseClick, doMouseDblClick, findCommonParent, foredate, gainedSelection, geometryChangeChild, getBoundingRect, getDocument, getDraggingObject, getFlags, getHeight, getLayer, getLeft, getLocation, getLocation, getParent, getParentJGoNode, getParentNode, getPartner, getRectangleSpotLocation, getSize, getSize, getSpotLocation, getSpotLocation, getToolTipText, getTop, getTopLeft, getTopLeft, getTopLevelObject, getView, getWidth, growRect, handleMove, handleResize, hideSelectionHandles, is4ResizeHandles, isAutoRescale, isBoundingRectInvalid, isChildOf, isDraggable, isDragsNode, isInitializing, isPointInObj, isResizable, isSelectable, isSkipsUndoManager, isSuspendUpdates, isTopLevel, isUpdatePartner, isVisible, lostSelection, partnerUpdate, pick, redirectSelection, remove, set4ResizeHandles, setAutoRescale, setBoundingRect, setBoundingRect, setBoundingRect, setBoundingRectInvalid, setBoundsRect, setDraggable, setDragsNode, setFlags, setHeight, setInitializing, setLeft, setLocation, setLocation, setLocationOffset, setLocationOffset, setParent, setPartner, setRectangleSpotLocation, setResizable, setSelectable, setSize, setSize, setSizeKeepingLocation, setSkipsUndoManager, setSpotLocation, setSpotLocation, setSpotLocation, setSpotLocationOffset, setSuspendUpdates, setTop, setTopLeft, setTopLeft, setUpdatePartner, setVisible, setWidth, showSelectionHandles, spotOpposite, update, update
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

StyleHidden

public static final int StyleHidden
The port will have no predefined visual representation

See Also:
Constant Field Values

StyleObject

public static final int StyleObject
The port will be shown with a JGo object

See Also:
Constant Field Values

StyleEllipse

public static final int StyleEllipse
The port will be drawn as an ellipse

See Also:
Constant Field Values

StyleTriangle

public static final int StyleTriangle
The port will be drawn as a triangle

See Also:
Constant Field Values

StyleRectangle

public static final int StyleRectangle
The port will be drawn as a rectangle

See Also:
Constant Field Values

StyleDiamond

public static final int StyleDiamond
The port will be drawn as a diamond

See Also:
Constant Field Values

ChangedStyle

public static final int ChangedStyle
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port style has changed

See Also:
Constant Field Values

ChangedObject

public static final int ChangedObject
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port object has changed

See Also:
Constant Field Values

ChangedValidSource

public static final int ChangedValidSource
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port's ability to act as a source for links (a link's "from" port) has changed

See Also:
Constant Field Values

ChangedValidDestination

public static final int ChangedValidDestination
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the port's ability to act as a destination for links (a link's "to" port) has changed

See Also:
Constant Field Values

ChangedFromSpot

public static final int ChangedFromSpot
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the link spot for links going from this port has changed

See Also:
Constant Field Values

ChangedToSpot

public static final int ChangedToSpot
a CHANGED JGoDocumentEvent or JGoViewEvent hint: the link spot for links going to this port has changed

See Also:
Constant Field Values

ChangedAddedLink

public static final int ChangedAddedLink
a CHANGED JGoDocumentEvent or JGoViewEvent hint: added a link

See Also:
Constant Field Values

ChangedRemovedLink

public static final int ChangedRemovedLink
a CHANGED JGoDocumentEvent or JGoViewEvent hint: removed a link

See Also:
Constant Field Values

ChangedEndSegmentLength

public static final int ChangedEndSegmentLength
a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed length of a link's end segment at this port

See Also:
Constant Field Values

ChangedValidSelfNode

public static final int ChangedValidSelfNode
a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed the ValidSelfNode property

See Also:
Constant Field Values

ChangedValidDuplicateLinks

public static final int ChangedValidDuplicateLinks
a CHANGED JGoDocumentEvent or JGoViewEvent hint: changed the ValidDuplicateLinks property

See Also:
Constant Field Values

ChangedPartID

public static final int ChangedPartID
a CHANGED JGoDocumentEvent or JGoViewEvent hint:

See Also:
Constant Field Values
Constructor Detail

JGoPort

public JGoPort()
Create a new port shown as an ellipse. The port will have no size, until its bounding rectangle is set.

By default ports are not Selectable or Resizable.


JGoPort

public JGoPort(org.eclipse.swt.graphics.Rectangle rect)
Create a new port with the given bounding rectangle. The port will have the default style, as an ellipse.

By default ports are not Selectable or Resizable.

Parameters:
rect - the bounding rectangle of the port.

JGoPort

public JGoPort(org.eclipse.swt.graphics.Point location,
               Dimension size)
Construct a port at the given location with the given size. The port will have the default style, as an ellipse.

By default ports are not Selectable or Resizable.

Parameters:
location - the top-left position, in document coordinates
size - the width and height, in document coordinates

JGoPort

public JGoPort(org.eclipse.swt.graphics.Rectangle rect,
               JGoObject object)
Create a new port with the given bounding rectangle. The port will have style StyleObject which means that it will have the appearance of the given JGoObject. The object's bounding rectangle will be changed to match the port's bounding rectangle, but the object will not become part of the document or the view.

By default ports are not Selectable or Resizable. The port object, if any, will also become not Selectable or Resizable or Draggable.

Parameters:
rect - the bounding rect of the port
object - the object to imitate
Method Detail

copyObject

public JGoObject copyObject(JGoCopyEnvironment env)
Create a new instance of this object. Links cannot be copied until after both ports have been copied.

Overrides:
copyObject in class JGoDrawable
Parameters:
env - the environment for the copy operation - keeps track of copied objects.

copyObjectDelayed

public void copyObjectDelayed(JGoCopyEnvironment env,
                              JGoObject newobj)
Description copied from class: JGoObject
For objects that require a second pass to complete the copying, this method is called after the first pass of copying all of the objects in JGoDocument.copyFromCollection.

This method need only be overridden by objects that refer to other independent objects. The problem usually is that during the call to copyObject, some of the objects that this object refers to might not yet have been copied. So it's best to add this object to the JGoCopyEnvironment's Delayeds collection in the call to copyObject, and then fix things up during the second pass in the call to this method, copyObjectDelayed.

For most objects, this method does nothing. For JGoLinks, however, it also makes sure both ports refer to the copied ports, and if the ports were not copied, it removes the link.

Overrides:
copyObjectDelayed in class JGoObject
Parameters:
env - a JGoCopyEnvironment that remembers the mapping of original objects to copied ones
newobj - the newly copied instance of this object

SVGWriteObject

public void SVGWriteObject(DomDoc svgDoc,
                           DomElement jGoElementGroup)
Description copied from interface: JGoXMLSaveRestore
Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGWriteDoc() for every JGoObject contained within a JGoDocument. The following example uses a JGoRectangle to illustrate the format of a generated SVG JGoObject:

<g>
<JGoClass class="com.nwoods.jgo.JGoRectangle"\>
<rect height="75" style="stroke:black;stroke-width:1;fill:rgb(255,0,0);" width="75" x="65" y="71"/>
<JGoClass class="com.nwoods.jgo.JGoDrawable" drawablebrush="jgoid1" drawablepen="jgoid2" embeddedpenbrush="false"/>
<JGoClass class="com.nwoods.jgo.JGoObject" obj_flags="1054"/>
</g>

Note that the entire JGoObject is enclosed in a group (<g>). Each subclass of the JGoObject is described by a <JGoClass> element, starting with the most specific class and moving to the more general. Each <JGoClass> element has a "class" attribute which defines the class name. Each <JGoClass> element may also have several other attributes which uniquely describe that state of that class. Following the <JGoClass> element, each class may also genereate any other elements that are required, including representations of contained objects and standard SVG elements such as the <rect> element shown in the above example. The generation of SVG elements in the output makes it possible for the output to be read by SVG viewers and other SVG aware applications. The information contained in the <JGoClass> elements allows us to accurately save and restore all the information in a particular JGoObject subclass.

If this class contains a reference to another object, call DomDoc.registerReferencingNode() to register that reference. This will cause the element representing the referenced object to be identified with a unique id attribute, and cause the element representing the referring object to have a user defined attribute containing a reference to that id. See DomDoc.registerReferencingNode() for more information.

Typically, an implementation of this method will generate a <JGoClass> element using the DomDoc.createJGoClassElement() method, adding whatever attributes are necessary to describe the class. It will then call its superclass so that the superclass can add its own <JGoClass> element and other information to jGoElementGroup within the DomDoc.

Refer to com.nwoods.jgo.examples.flower.ActivityNode.SVGWriteObject() and com.nwoods.jgo.examples.SimpleNode.SVGWriteObject() for examples using this method.

Refer to the file com.nwoods.jgo.svg\xsvg.dtd for a formal description of JGo extensions to the SVG document type.

Specified by:
SVGWriteObject in interface JGoXMLSaveRestore
Overrides:
SVGWriteObject in class JGoDrawable

SVGReadObject

public DomNode SVGReadObject(DomDoc svgDoc,
                             JGoDocument jGoDoc,
                             DomElement svgElement,
                             DomElement jGoChildElement)
Description copied from interface: JGoXMLSaveRestore
Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() for every <JGoClass> element encountered in a DomDoc. First, an object of the type specified by the class attribute will be created and then the SVGReadObject() method will be called on that newly created object. Refer to SVGWriteObject() for a description of the expected format of the SVG document.

This method may also be called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() when reading any SVG document, including those not generated by JGo and therefore not containing any <JGoClass> elements. In such cases, the DefaultDocument.SVGReadElement() method may be subclassed to examine the SVG element and cause the appropriate JGoObject to be created to represent that element and call SVGReadObject() on that newly created object. By default, standard JGoObjects such as JGoRectangles, JGoStrokes, etc will be created to represent these objects.

If this class contains a reference to another object, call DomDoc.registerReferencingObject() to register that reference. This will cause the JGoObject.SVGUpdateReference() to be called on the referencing object after all the objects have been created, passing in the object befing referenced. See DomDoc.registerReferencingObject() for more information.

Typically, an implementation of this method starts by verifying that the element being read is a <JGoClass> element (which will be true if jGoChildElement is not null). This will always be true unless you have subclassed the DefaultDocument.SVGReadElement() method as described above. It will then read the expected attributes of the <JGoClass> element (as written by SVGReadObject()), call SVGReadObject() on its superclass, and finally return the next element by calling svgElement.getNextSibling().

Refer to com.nwoods.jgo.examples.flower.ActivityNode.SVGReadObject() and com.nwoods.jgo.examples.SimpleNode.SVGReadObject() for examples using this method.

Specified by:
SVGReadObject in interface JGoXMLSaveRestore
Overrides:
SVGReadObject in class JGoDrawable

SVGUpdateReference

public void SVGUpdateReference(java.lang.String attr,
                               java.lang.Object referencedObject)
Description copied from class: JGoObject
This method will be called to fill in object references.

This is called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc() after all the objects have been created and if DomDoc.registerReferencingObject() has been previously called by SVGReadObject().

Typically, an implementation of this method will first call the superclass and then fill in the appropriate object reference based on the attr argument.

Refer to com.nwoods.jgo.examples.SimpleNode.SVGWriteObject() for an example using this method.

Overrides:
SVGUpdateReference in class JGoDrawable

paint

public void paint(Graphics2D g,
                  JGoView view)
Draws the port depending on what style it is.

By default ports are drawn as ellipses.

For all styles except Hidden and Object, use setPen() and setBrush() to modify the appearance (typically just the color) of the port.

Overrides:
paint in class JGoObject
Parameters:
g - the graphics context.
view - the view we're drawing in

paintGreek

public boolean paintGreek(Graphics2D g,
                          JGoView view)
This method is called by paint to allow optimizing drawing a lot of objects at small scales. By default this will not draw anything at all for this port when the scale is at or less than getDefaultPaintNothingScale(), and it will only draw a small box when the scale is at or less than getDefaultPaintGreekScale().

Returns:
true if this method handled the painting, or false if it expects the normal painting to occur.

expandRectByPenWidth

public void expandRectByPenWidth(org.eclipse.swt.graphics.Rectangle rect)
Modify the given rectangle to account for any likely drawing beyond the bounds of the rectangle caused by wide pens. If there's a JGoObject representing the port, we probably need to account for its pen.

Overrides:
expandRectByPenWidth in class JGoDrawable
Parameters:
rect - a rectangle to be modified

getNearestIntersectionPoint

public boolean getNearestIntersectionPoint(int px,
                                           int py,
                                           int cx,
                                           int cy,
                                           org.eclipse.swt.graphics.Point result)
Description copied from class: JGoDrawable
Consider the pen width in determining the nearest intersection point.

Overrides:
getNearestIntersectionPoint in class JGoDrawable

getPartID

public int getPartID()
Description copied from interface: JGoIdentifiablePart
Return the integer PartID for this JGoObject that is in a JGoDocument.

Specified by:
getPartID in interface JGoIdentifiablePart

setPartID

public void setPartID(int id)
Description copied from interface: JGoIdentifiablePart
Change the PartID for a JGoObject; this is normally only called by JGoDocument code when this object is added to a document layer.

Specified by:
setPartID in interface JGoIdentifiablePart

getStyle

public int getStyle()
Returns the current style of the port. See the paint method description for a list of port styles.

Returns:
the current style of the port

setStyle

public void setStyle(int s)
Sets the current style of the port. See the paint method description for a list of port styles. Port styles cannot be combined.

Parameters:
s - a new style for the port

getPortObject

public JGoObject getPortObject()
Returns the current PortObject. The PortObject defines the appearance of a port only if the Style is StyleObject. getPortObject() may return null if a current PortObject has not been defined.

Returns:
the PortObject of the port

setPortObject

public void setPortObject(JGoObject obj)
Sets the current PortObject. The PortObject defines the appearance of a port only if the Style is StyleObject.

The new object may not be an instance of JGoControl or JGoPort.

Parameters:
obj - the PortObject of the port

getNumLinks

public int getNumLinks()
Returns the number of links currently attached to this port.


getNumFromLinks

public int getNumFromLinks()
Returns the number of links coming from this port. The count does not include temporary links (links in the process of being interactively created)


getNumToLinks

public int getNumToLinks()
Returns the number of links coming to this port.


hasNoLinks

public boolean hasNoLinks()
This predicate indicates whether there are any links attached to this port.


getFirstLinkPos

public JGoListPosition getFirstLinkPos()
Return the position of the first link in the collection of links connected to this port. This returns null if there are no links connected at this port.


getLinkAtPos

public JGoLink getLinkAtPos(JGoListPosition pos)
Return the link at the specified position in the collection of links connected to this port.

Parameters:
pos - the position of the link in the collection.
Returns:
the link specified by the given position.

getNextLinkPos

public JGoListPosition getNextLinkPos(JGoListPosition pos)
Return the position of the next link in the collection of links connected to this port.

Parameters:
pos - the position previous to the link position to be returned.
Returns:
the position of the next link in the collection of links connected to this port.

removeAllLinks

public void removeAllLinks()
This convenience method unlinks all links attached to this port.


getLinkPoint

public org.eclipse.swt.graphics.Point getLinkPoint(int spot,
                                                   org.eclipse.swt.graphics.Point result)
Given a particular spot, return where the link should connect up to on this port. The possible spots are given by the JGoObject spot locations.

You may wish to override this method to return points that are not on the port's bounding rectangle and to handle the NoSpot case, for handling custom cases which do not correspond to the predefined spots.

Parameters:
spot - the spot on which to link
result - a Point that will be modified to have the point to link to, in document coordinates; if result is null a Point will be allocated
Returns:
the Point to connect links to; this is the modified argument result or else a newly allocated Point

getLinkPoint

public final org.eclipse.swt.graphics.Point getLinkPoint(int spot)
Given a particular spot, return where the link should connect up to on this port. The possible spots are given by the JGoObject Spot locations. NoSpot means that any direction is acceptable.

This is a convenience method that allocates a new Point; you may find calling getLinkPoint(int, Point) more efficient.

Parameters:
spot - the spot on which to link
Returns:
the Point to connect links to

getLinkPointFromPoint

public org.eclipse.swt.graphics.Point getLinkPointFromPoint(int x,
                                                            int y,
                                                            org.eclipse.swt.graphics.Point result)
Return the point where a link coming from the given point should connect. This is normally called when the spot is NoSpot, so any direction would be reasonable.

This returns a point on the edge of the bounding rectangle of this port that is the intersection of the edge with a straight line running from (x, y) to the center point. In earlier versions, this returned the center point.

You may want to override this in order to control where links appear to touch the port. The point might not even be within the bounding rectangle of the port.

Parameters:
x - the X position of a point on the other end of the link
y - the Y position of a point on the other end of the link
result - a Point that will be modified to have the point to link to, in document coordinates; if result is null a Point will be allocated
Returns:
the custom link point; this is the modified argument result or else a newly allocated Point

getFromLinkPoint

public org.eclipse.swt.graphics.Point getFromLinkPoint(JGoLink link,
                                                       org.eclipse.swt.graphics.Point result)
Return the point where the given outgoing link should connect to this port.

When getFromSpot() returns a spot other than NoSpot, this method returns the result of calling getLinkPoint for that spot. When the spot is NoSpot and the link is Orthogonal, this method returns the result of calling getLinkPointFromPoint for a point far away along the appropriate axis relative to this port's center. If the link is not Orthogonal, this returns the result of calling getLinkPointFromPoint on the next-to-last point in the link's stroke.

Parameters:
link - a JGoLink; if this is null, the center of this port is returned
result - a Point that is modified to hold the result; if null, a Point is allocated and returned
Returns:
the connection point for the link; this is the modified argument point or else a newly allocated Point

getFromLinkPoint

public final org.eclipse.swt.graphics.Point getFromLinkPoint(org.eclipse.swt.graphics.Point result)
Return the point where links whose source is this port should connect to this port.

Parameters:
result - a Point that will be modified to have the point to link to, in document coordinates; if result is null a Point will be allocated
Returns:
the connection point for links going out; this is the modified argument point or else a newly allocated Point

getFromLinkPoint

public final org.eclipse.swt.graphics.Point getFromLinkPoint()
Return the point where links whose source is this port should connect to this port.

This is a convenience method that allocates a new Point; you may find calling getFromLinkPoint(Point) more efficient.

Returns:
the connection point for links going out; this is a newly allocated Point

getToLinkPoint

public org.eclipse.swt.graphics.Point getToLinkPoint(JGoLink link,
                                                     org.eclipse.swt.graphics.Point result)
Return the point where the given incoming link should connect to this port.

When getToSpot() returns a spot other than NoSpot, this method returns the result of calling getLinkPoint for that spot. When the spot is NoSpot and the link is Orthogonal, this method returns the result of calling getLinkPointFromPoint for a point far away along the appropriate axis relative to this port's center. If the link is not Orthogonal, this returns the result of calling getLinkPointFromPoint on the next-to-last point in the link's stroke.

Parameters:
link - a JGoLink; if this is null, the center of this port is returned
result - a Point that is modified to hold the result; if null, a Point is allocated and returned
Returns:
the connection point for the link; this is the modified argument point or else a newly allocated Point

getToLinkPoint

public final org.eclipse.swt.graphics.Point getToLinkPoint(org.eclipse.swt.graphics.Point result)
Return the point where links whose destination is this port should connect to this port.

Parameters:
result - a Point that will be modified to have the point to link to, in document coordinates; if result is null a Point will be allocated
Returns:
the connection point for links coming in; this is the modified argument result or else a newly allocated Point

getToLinkPoint

public final org.eclipse.swt.graphics.Point getToLinkPoint()
Return the point where links whose destination is this port should connect to this port.

This is a convenience method that allocates a new Point; you may find calling getToLinkPoint(Point) more efficient.

Returns:
the connection point for links coming in; this is a newly allocated Point

getFromSpot

public int getFromSpot()
Return the spot of the port at which to connect links coming from this port.


setFromSpot

public void setFromSpot(int spot)
Set which spot of the port is to be used to connect links coming from this port.

Parameters:
spot - the spot of the port to be used to connect links coming from this port.

getToSpot

public int getToSpot()
Return the spot of the port at which to connect links going to this port.


setToSpot

public void setToSpot(int spot)
Set which spot of the port is to be used to connect links going to this port.

Parameters:
spot - the spot of the port to be used to connect links going to this port.

getLinkDir

public double getLinkDir(int spot)
Given a spot, return the direction in radians of the first segment of the link. The possible values of spots are the Spot locations of JGoObject. This returns -1 when the spot is actually Center.

Parameters:
spot - a constant indicating the port spot.
Returns:
the direction in radians of the first segment of the link on the given spot.

getFromLinkDir

public double getFromLinkDir()
Return the direction in radians of the first segment of links coming from this port.


getToLinkDir

public double getToLinkDir()
Return the direction in radians of the first segment of links going to this port.


getFromLinkDir

public double getFromLinkDir(JGoLink link)
Determine the direction, in radians, that a link will go when coming out of this port.

When the value of getFromSpot() is not JGoObject.NoSpot or JGoObject.Center, this just returns the result of calling getFromLinkDir(), ignoring the link argument. Otherwise this returns one of the horizontal or vertical directions, based on the relative positions of the link's other port. You may wish to override this method if you want to customize dynamically the direction of the link at the link point.


getToLinkDir

public double getToLinkDir(JGoLink link)
Determine the direction, in radians, that a link will go when going into this port.

When the value of getToSpot() is not JGoObject.NoSpot or JGoObject.Center, this just returns the result of calling getToLinkDir(), ignoring the link argument. Otherwise this returns one of the horizontal or vertical directions, based on the relative positions of the link's other port. You may wish to override this method if you want to customize dynamically the direction of the link at the link point.


validLink

public boolean validLink(JGoPort to)
Return whether or not a link from this port to "to" is valid.

By default, every link is valid as long as both ports are visible, this port isValidSource() and the "to" port isValidDestination(), either both ports have isValidSelfNode() true or both ports are not in the same node, and either both ports have isValidDuplicateLinks() true or there is not already a link from this port to "to".

This method is called from JGoView.validLink(JGoPort from, JGoPort to). The result is cached on this object during a user's drawing of a link, and is available by isValidLink(). Subclasses should override to get more interesting behavior, either here on JGoPort or on JGoView.validLink().

Parameters:
to - the destination port
Returns:
true if the link would be valid

isValidLink

public boolean isValidLink()
This predicate is true when JGoView.validLink() returned true between the originating port and this port. The predicate is only valid between a call to JGoView.startNewLink() and the JGoView.newLink() or JGoView.noNewLink() methods.

The ValidLink property is used to cache whether this particular port is a valid source or destination for the user's ongoing press-drag process of deciding where to make a link. The cache is normally desirable because the computation for deciding validity may be very expensive.


canLinkFrom

public boolean canLinkFrom()
This predicate should be true if, by itself, there is no known reason why one couldn't create a valid link from this port to some port.

See Also:
validLink(JGoPort)

canLinkTo

public boolean canLinkTo()
This predicate should be true if, by itself, there is no known reason why one couldn't create a valid link from some port to this one.

See Also:
validLink(JGoPort)

isValidSource

public boolean isValidSource()
Return whether or not a link can start at this port, as the potential "from" port for a link.

By default, all ports are valid sources for links. This is called from JGoView, deciding if the user can begin drawing a link from this port to another one. You can set this property for each port object, or you can override this method to get more interesting behavior, or you can override JGoView.validSourcePort().

Returns:
true if the link should be considered

setValidSource

public void setValidSource(boolean valid)
Set whether the user can draw a link with this port as the "from" end of the link.


isValidDestination

public boolean isValidDestination()
Return whether or not a link can end at this port, as the potential "to" port for a link.

By default, all ports are valid destinations for links. This is called from JGoView, deciding if the user can begin drawing a link "backwards" from this port. You can set this property for each port object, or you can override this method to get more interesting behavior. or you can override JGoView.validDestinationPort().

Returns:
true if the link should be considered

setValidDestination

public void setValidDestination(boolean valid)
Set whether the user can draw a link with this port as the "to" end of the link.


isValidSelfNode

public boolean isValidSelfNode()
Returns whether a valid link can be made between two ports belonging to the same node.

The isValidLink method uses this property in the following manner: If this property is true, and the other port's isValidSelfNode() is also true, then the proposed link may be valid. Otherwise, if isInSameNode() is true, it will not be a valid link.

The default value is false.


setValidSelfNode

public void setValidSelfNode(boolean valid)
Change whether a link may be valid to another port that is part of the same node as this port.


isInSameNode

public static boolean isInSameNode(JGoPort a,
                                   JGoPort b)
This static method determines if both ports belong to the same node.

This uses JGoObject.getParentNode() to find the highest level parent object other than JGoSubGraphs. If either parameter is null, this returns false.


isInSameNode

public boolean isInSameNode(JGoPort p)
Determine whether this port is in the "same" node as another port.

By default, this just calls JGoPort.isInSameNode(this, p).


isValidDuplicateLinks

public boolean isValidDuplicateLinks()
Return whether a valid link can be made between two ports already connected by a link.

The isValidLink method uses this property in the following manner: If this property is true, and the other port's isValidDuplicateLinks() is also true, then the proposed link may be valid. Otherwise, if isLinked() is true, it will not be a valid link.

The default value is false.


setValidDuplicateLinks

public void setValidDuplicateLinks(boolean valid)
Change whether duplicate links to another port may be valid at this port.


isLinked

public static boolean isLinked(JGoPort a,
                               JGoPort b)
This static method determines if there is a link going from one port to another.

This is true if there is a JGoLink from A to B. Note that a link in the opposite direction will not satisfy this predicate. If either parameter is null, this returns false.


isLinked

public boolean isLinked(JGoPort p)
Determine whether there is already a link from this port to another port.

By default, this just calls JGoPort.isLinked(this, p). Note that a link in the opposite direction, that is one whose JGoLink.getFromPort() is P and whose JGoLink.getToPort() is this port, will not satisfy this predicate.

If you do not want to permit two links, one link in each direction, perhaps because you want to think of the links as being directionless, then you can override this method as follows:

 public boolean isLinked(JGoPort p) {
   return JGoPort.isLinked(this, p) || JGoPort.isLinked(p, this);
 }
 


geometryChange

protected void geometryChange(org.eclipse.swt.graphics.Rectangle prevRect)
Called just after the bounding rectangle for this object has been changed. This is a hook for subclasses to get notification and perform processing when their dimensions change.

It also calls portChange(), so that any connected links have a chance to redraw.

Overrides:
geometryChange in class JGoObject

portChange

public void portChange(int hint,
                       int prevInt,
                       java.lang.Object prevVal)
Called whenever any change happens to a port that may require the links connected to this port to be modified (move, resize, etc).

By default this calls portChange() on each connected JGoLink.


linkChange

public void linkChange()
Called whenever a link has been added or removed from this port.

By default this method does nothing.


ownerChange

protected void ownerChange(JGoObjectCollection oldOwner,
                           JGoObjectCollection newOwner,
                           JGoObject mainObject)
Called whenever this object's owner (JGoView or JGoDocument) changes.

By default, when a port is removed from a collection, all of its attached links are unlinked.

Overrides:
ownerChange in class JGoObject
Parameters:
oldOwner - the previous owner object
newOwner - the new owner object
mainObject - the object being inserted or removed from the document or view

doUncapturedMouseMove

public boolean doUncapturedMouseMove(int flags,
                                     org.eclipse.swt.graphics.Point dc,
                                     org.eclipse.swt.graphics.Point vc,
                                     JGoView view)
Called when the mouse moves over this port --- we set the current cursor to be a Hand if the user can start drawing a new link at this port.

Overrides:
doUncapturedMouseMove in class JGoObject
Parameters:
flags - event specific flags
dc - the point of the click in document coordinates
vc - the point of the click in view coordinates
view - the view in which this event occured
Returns:
true if handled here and the view doesn't need to try this object's parent to see if it's interested
See Also:
JGoView.doUncapturedMouseMove(int, org.eclipse.swt.graphics.Point, org.eclipse.swt.graphics.Point)

getEndSegmentLength

public int getEndSegmentLength()
Return how long a line to draw straight out from the port before "turning" (assuming non-orthogonal routing and a non-Center direction for links).


setEndSegmentLength

public void setEndSegmentLength(int len)
Set how long a straight segment there should be for links at this port if the spot is not NoSpot.


copyNewValueForRedo

public void copyNewValueForRedo(JGoDocumentChangedEdit e)
Description copied from class: JGoObject
This method is called when a JGoDocumentChangedEdit is created for a JGoDocumentEvent.CHANGED event, when a JGoObject has been changed. In order for the JGoDocumentChangedEdit to be able to perform a redo, it needs to remember the new property value or state. However, the JGoObject.update method does not provide such a new value. The value must be taken from this object and copied into the JGoDocumentChangedEdit by calling setNewValue and/or setNewValueInt.

Just as the previous/old value/state information is stored as one or both of an integer and an Object, the new value/state information may be stored as either or both of an integer or an Object.

The responsibility for copying rests with the document event listener rather than the code calling JGoObject.update for efficiency when there is no undo/redo manager.

Overrides:
copyNewValueForRedo in class JGoDrawable

changeValue

public void changeValue(JGoDocumentChangedEdit e,
                        boolean undo)
Description copied from class: JGoObject
This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the property value change for a JGoObject.

You will want to override this method to handle changing the additional state of your object subclasses.

Overrides:
changeValue in class JGoDrawable

getDefaultPaintNothingScale

public static double getDefaultPaintNothingScale()
Return the view scale at which a text object should not paint anything. Thus when a JGoText object is painted on a view whose scale is less than or equal to this value, nothing actually appears.


setDefaultPaintNothingScale

public static void setDefaultPaintNothingScale(double s)
Change the scale at which text will not paint. Calling this method will not actually repaint any views or any JGoText objects.


getDefaultPaintGreekScale

public static double getDefaultPaintGreekScale()
Return the view scale at which this text object should paint something simpler than real text.


setDefaultPaintGreekScale

public static void setDefaultPaintGreekScale(double s)
Change the scale at which text will paint very simply. Calling this method will not actually repaint any views or any JGoText objects.