com.nwoods.jgo
Class JGoDocument

java.lang.Object
  extended bycom.nwoods.jgo.JGoDocument
All Implemented Interfaces:
JGoObjectCollection, JGoObjectSimpleCollection, JGoXMLSaveRestore, java.io.Serializable

public class JGoDocument
extends java.lang.Object
implements JGoObjectCollection, java.io.Serializable, JGoXMLSaveRestore

JGoDocument represents a group of JGoObjects that can be viewed inside a JGoView. JGoDocument represents the model in the model-view-controller architecture; JGoView plays the role of the view and as a default controller.

The JGoDocument should be thought of as an ordered list of objects. The objects are drawn in sequential order, so objects at the beginning of the list appear "behind" objects that are at the end. You can add, remove, and iterate over the document's objects by using the document's implementation of the JGoObjectCollection interface.

The JGoObjects held in the document have a size and position. The coordinate system used by the document just comes from the units used by its objects. JGoViews have a coordinate system that may be translated and scaled from that of the document, so as to support panning and zooming. The document's size is automatically expanded to encompass all of its objects.

The document keeps track of all registered JGoDocumentListeners. JGoView is a predefined implementor of JGoDocumentListener. It needs to notice when document objects change so that it can update the visible rendering of those objects. You can register your own listeners to notice changes to the document or its objects. The fireUpdate() method actually does the notification of all document listeners.

You can add a copy of a collection of objects to a document by calling copyFromCollection(). The way objects are copied is controlled by the copyObject() methods of all the copied objects and by the JGoCopyEnvironment. The JGoCopyEnvironment also holds the results of the copying.

In addition to all of the objects held by the document, the document has its own notion of the background color, called the paper color. This is independent of the JGoView Background color, which affects the view's border. The paper color takes precedence over the view's Background color. This permits the view to specify the color when the PaperColor is null.

In order to work out-of-the-box with the clipboard and with drag-and-drop, JGoDocument implements Serializable. Your subclasses derived from JGoDocument and JGoObject also need to be serializable.

Serialized objects will not be compatible with future JGo releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of JGo.

JGoDocument is not thread-safe.

There are methods to add, re-order, and remove layers from a document, and to get the first, next, previous, and last layers. Each document also has a defaultLayer property, which is used by methods that need to create objects in a document but do not know which layer to put them in.

To turn on undo/redo functionality, create an instance of JGoUndoManager and call the document's setUndoManager method. The JGoUndoManager is a document listener that records all changes to document properties and the document's objects. Those change records are implemented as JGoDocumentChangedEdits and are accumulated in a CompoundEdit for each user's mouse action, bounded by calls to startTransaction and endTransaction.

Your application will want to call the canUndo and canRedo predicates and the undo and redo methods. You may want to call discardAllEdits when the document is saved, to avoid accumulating too much undo state.

If you extend JGoDocument in a class that has its own additional properties, be sure to override copyOldValueForUndo, copyNewValueForRedo, and changeValue appropriately. These methods are responsible for handling each of the JGoDocumentEvent hints, and are similar to methods added to JGoObject for the JGoDocumentEvent.CHANGED hint. Each mutating method must call fireUpdate with a uniquely identifying hint and with the previous value.

The documentSize property now includes objects that are at negative coordinate positions. The documentTopLeft property has been added so that you can tell where the document now starts; the initial value is (0,0).

See Also:
JGoView, JGoDocumentEvent, JGoDocumentListener, JGoDocumentChangedEdit, JGoUndoManager, JGoLayer, JGoObject, JGoArea, JGoObjectCollection, Serialized Form

Field Summary
static int CyclesAllowAll
          A constant value for specifying the cycles allowed in graphs.
static int CyclesDestinationTree
          A constant value for specifying the cycles allowed in graphs.
static int CyclesNotDirected
          A constant value for specifying the cycles allowed in graphs.
static int CyclesNotDirectedFast
          A constant value for specifying the cycles allowed in graphs.
static int CyclesNotUndirected
          A constant value for specifying the cycles allowed in graphs.
static int CyclesSourceTree
          A constant value for specifying the cycles allowed in graphs.
 
Constructor Summary
JGoDocument()
          Construct a new document object.
 
Method Summary
 void add(JGoObject obj)
          Add an object to the default layer, or to the links layer if the given object is a JGoLink.
 JGoObject addCopy(JGoObject obj, org.eclipse.swt.graphics.Point loc)
          Add a copy of an object into this document at the given point.
 void addDocumentListener(JGoDocumentListener l)
          Add a listener for JGoDocument events.
 JGoLayer addLayerAfter(JGoLayer old)
          Create a new empty layer and add it to this document just in front of the given layer.
 JGoLayer addLayerBefore(JGoLayer old)
          Create a new empty layer and add it to this document just behind the given layer.
 JGoListPosition addObjectAtHead(JGoObject obj)
          Adds an object behind all other objects in the document.
 JGoListPosition addObjectAtTail(JGoObject obj)
          Adds an object in front of all other objects in the document.
 void bringLayerToFront(JGoLayer layer)
          Re-order the layers of this document by moving the given one in front of all of the others.
 void bringObjectToFront(JGoObject obj)
          Moves an object in front of other objects in the document (moved to the end of the list of objects).
 boolean canRedo()
          This predicate is delegated to the document's UndoManager, if any.
 boolean canUndo()
          This predicate is delegated to the document's UndoManager, if any.
 void changeValue(JGoDocumentChangedEdit e, boolean undo)
          This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the state change.
 org.eclipse.swt.graphics.Rectangle computeBounds()
          Call computeBounds on the contents of this document.
static org.eclipse.swt.graphics.Rectangle computeBounds(JGoObjectSimpleCollection coll)
          Determine the smallest rectangle that encloses all of the visible objects in the given collection.
 JGoCopyEnvironment copyFromCollection(JGoObjectSimpleCollection coll)
          Copy the JGoObjects in the given collection into this document.
 JGoCopyEnvironment copyFromCollection(JGoObjectSimpleCollection coll, org.eclipse.swt.graphics.Point offset, JGoCopyEnvironment map)
          Copy the JGoObjects in the given collection into this document.
 void copyNewValueForRedo(JGoDocumentChangedEdit e)
          This method is called when a JGoDocumentChangedEdit is created.
 void copyOldValueForUndo(JGoDocumentChangedEdit e)
          This method is called when a JGoDocumentChangedEdit is created.
 JGoCopyEnvironment createDefaultCopyEnvironment()
          Return an appropriate copy environment for copying objects to this document.
 void deleteContents()
          Removes all the objects and all layers (but the first one) from the document.
 void discardAllEdits()
          This method is delegated to the document's UndoManager, if any.
 void endTransaction(boolean commit)
          This method is delegated to the document's UndoManager, if any.
 void endTransaction(java.lang.String pname)
          This method is delegated to the document's UndoManager, if any.
 void ensureUniquePartID()
          Make sure all of the objects in this document that implement JGoIdentifiablePart have unique PartID.
 JGoLayer findLayer(java.lang.Object identifier)
          Return a layer whose identifier equals the given identifier argument.
 JGoListPosition findObject(JGoObject obj)
          Return the position of a specific object in the collection.
 JGoIdentifiablePart findPart(int id)
          Return the JGoIdentifiablePart in this document with the given PartID, if any.
 void fireForedate(int hint, int flags, java.lang.Object obj)
          This method should be called to notify all document listeners about an event that is about to happen.
 void fireUpdate(int hint, int flags, java.lang.Object object, int prevInt, java.lang.Object prevObj)
          Notify all interested parties of modifications to the JGoDocument.
 org.eclipse.swt.graphics.Rectangle getAvoidableRectangle(JGoObject obj, org.eclipse.swt.graphics.Rectangle rect)
          For an object that is assumed to be isAvoidable(), return the rectangle that the object should occupy.
 JGoLayer getDefaultLayer()
          Return the default layer for creating new objects by methods that do not explicitly state which layer to use.
 JGoDocumentListener[] getDocumentListeners()
          Return an array of the JGoDocumentListeners that are currently listening for JGoDocumentEvents on this document.
 Dimension getDocumentSize()
          Get the document size in document coordinates.
 org.eclipse.swt.graphics.Point getDocumentTopLeft()
          Get the top-left corner of the document, in document coordinates.
 JGoLayer getFirstLayer()
          Return the bottom-most layer of objects in this document.
 JGoListPosition getFirstObjectPos()
          Return the position of the first object in the collection.
 JGoLayer getLastLayer()
          Return the top-most layer of objects in this document.
 JGoListPosition getLastObjectPos()
          Return the position of the last object in the collection.
 JGoLayer getLinksLayer()
          Return the layer that by convention holds links.
 JGoLayer getNextLayer(JGoLayer layer)
          Return the layer just above the given layer.
 JGoListPosition getNextObjectPos(JGoListPosition pos)
          Return the next object position, recursing into any JGoAreas.
 JGoListPosition getNextObjectPosAtTop(JGoListPosition pos)
          Return the position for the next top-level object in the collection.
 int getNumLayers()
          Return the number of layers in this document.
 int getNumObjects()
          Returns the number of top-level objects in the document.
 JGoObject getObjectAtPos(JGoListPosition pos)
          Return the object for the given position.
 org.eclipse.swt.graphics.RGB getPaperColor()
          Gets the background (paper) color.
 JGoLayer getPrevLayer(JGoLayer layer)
          Return the layer just below the given layer.
 JGoListPosition getPrevObjectPos(JGoListPosition pos)
          Return the position of the previous object in the collection.
 JGoUndoManager getUndoManager()
          Return the JGoUndoManager that is responsible for tracking all changes to this document.
 int getValidCycle()
          Gets whether a valid link can be made between two ports that may produce a directed or undirected cycle in this document.
 void insertLayerAfter(JGoLayer old, JGoLayer insert)
          Re-order the layers of this document by moving a layer in front of another one.
 void insertLayerBefore(JGoLayer old, JGoLayer insert)
          Re-order the layers of this document by moving a layer behind another one.
 JGoListPosition insertObjectAfter(JGoListPosition pos, JGoObject obj)
          Adds an object to the document after the given position.
 JGoListPosition insertObjectBefore(JGoListPosition pos, JGoObject obj)
          Adds an object to the document before the given position.
 boolean isAvoidable(JGoObject obj)
          This predicate determines whether the search for a route for a link whose isAvoidsNodes() property is true will try to go around the given object.
 boolean isEmpty()
          Returns true if the document contains no objects.
 boolean isMaintainsPartID()
          Return whether this document makes sure each JGoIdentifiablePart gets a unique PartID when it is added to the document.
 boolean isModifiable()
          Return whether the user can modify this document interactively.
 boolean isSkipsUndoManager()
          Return whether the UndoManager (if any) should stop recording any changes to this document.
 boolean isSuspendUpdates()
          Return whether this document is not automatically updated when it is changed.
 boolean isUnoccupied(org.eclipse.swt.graphics.Rectangle r, JGoObject skip)
          Returns true if there are any "avoidable" objects within or intersecting the given rectangular region.
static boolean makesDirectedCycle(JGoNode a, JGoNode b)
          This method returns true if adding a link from a to b would result in a cycle of directed links going through the node a.
static boolean makesDirectedCycleFast(JGoNode a, JGoNode b)
          This method returns true if adding a link from a to b would result in a cycle of directed links going through the node a.
static boolean makesUndirectedCycle(JGoNode a, JGoNode b)
          This method returns true if adding a link from a to b would result in a cycle or loop of links, regardless of link direction, going through the node a.
 JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck, boolean selectableOnly)
          Given a point in document coordinates, return the topmost object that contains that point.
 java.util.ArrayList pickObjects(org.eclipse.swt.graphics.Point p, boolean selectableOnly, java.util.ArrayList coll, int max)
          Return a list of all the JGoObjects that contain a given point.
 void redo()
          This method is delegated to the document's UndoManager, if any.
 void removeAll()
          Remove all objects from this document without removing any layers.
 void removeDocumentListener(JGoDocumentListener l)
          Remove a listener for JGoDocument events.
 void removeLayer(JGoLayer layer)
          Remove all of the given layer's objects from this document, and then remove the layer itself from this document.
 void removeObject(JGoObject obj)
          Removes an object from the document.
 JGoObject removeObjectAtPos(JGoListPosition pos)
          Remove an object at specified position from the collection.
 void sendLayerToBack(JGoLayer layer)
          Re-order the layers of this document by moving the given one behind all of the others.
 void sendObjectToBack(JGoObject obj)
          Moves an object behind other objects in the document (moved to the head of the list of objects).
 void setDefaultLayer(JGoLayer layer)
          Change the default layer used to hold newly created objects created by copyFromCollection (and thus by JGoView.paste).
 void setDocumentSize(Dimension size)
          Set the document size in document coordinates.
 void setDocumentSize(int width, int height)
          Set the document size in document coordinates.
 void setDocumentTopLeft(int x, int y)
          Set the document top-left corner in document coordinates.
 void setDocumentTopLeft(org.eclipse.swt.graphics.Point topleft)
          Set the document top-left corner in document coordinates.
 void setLinksLayer(JGoLayer layer)
          Change the layer to be used by convention to hold links.
 void setMaintainsPartID(boolean bFlag)
          Change whether this document assigns a unique PartID to each JGoIdentifiablePart as it is added to the document.
 void setModifiable(boolean b)
          Change whether the user is able to modify this document.
 void setPaperColor(org.eclipse.swt.graphics.RGB col)
          Sets the background (paper) color.
 void setSkipsUndoManager(boolean bFlag)
          Control whether the UndoManager records any changes to this document.
 void setSuspendUpdates(boolean bFlag)
          Change whether the screen is updated and document listeners are notified in response to any change to the document or to any objects in this document.
 void setUndoManager(JGoUndoManager m)
          Specify the JGoUndoManager that should be responsible for tracking all changes to this document and all of its objects.
 void setValidCycle(int validCycle)
          Sets whether a valid link can be made between two ports that may produce a directed or undirected cycle in this document.
 void sortByZOrder(JGoObject[] a)
          Sort an Array of JGoObjects by their Z-order position in the layers of this document.
 void startTransaction()
          This method is delegated to the document's UndoManager, if any.
 DomNode SVGReadLayer(DomDoc svgDoc, JGoDocument jGoDoc, DomElement svgElement, DomElement jGoChildElement, JGoLayer layer)
          Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 DomNode SVGReadObject(DomDoc svgDoc, JGoDocument jGoDoc, DomElement svgElement, DomElement jGoChildElement)
          Read a DomElement containing the JGoDocument properties from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void SVGUpdateReference(java.lang.String attr, java.lang.Object referencedObject)
           
 void SVGWriteLayer(DomDoc svgDoc, DomElement jGoElementGroup, JGoLayer layer)
          Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void SVGWriteObject(DomDoc svgDoc, DomElement jGoElementGroup)
          Write a DomElement containing the JGoDocument properties out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void undo()
          This method is delegated to the document's UndoManager, if any.
 void update()
          Cause all views to be updated.
protected  void updateDocumentSize(JGoObject obj)
          Corrects the document size and top-left for an object being added or moved.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CyclesAllowAll

public static final int CyclesAllowAll
A constant value for specifying the cycles allowed in graphs. This value indicates no restrictions on cycles, except when imposed byJGoPort.isValidSelfNode() or JGoPort.isValidDuplicateLinks(). This is the default for JGoDocument.isValidCycle().

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values

CyclesNotDirected

public static final int CyclesNotDirected
A constant value for specifying the cycles allowed in graphs. This value indicates a valid link from a port will not produce a directed cycle in the graph. This option uses JGoDocument.MakesDirectedCycle() in the implementation of JGoPort.validLink().

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values

CyclesNotDirectedFast

public static final int CyclesNotDirectedFast
A constant value for specifying the cycles allowed in graphs. This value indicates a valid link from a port will not produce a directed cycle in the graph, assuming there are no directed cycles anywhere accessible from either port. This option uses JGoDocument.MakesDirectedCycleFast() in the implementation of JGoPort.validLink()

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values

CyclesNotUndirected

public static final int CyclesNotUndirected
A constant value for specifying the cycles allowed in graphs. This value indicates a valid link from a port will not produce an undirected cycle in the graph. Traversal of all links during the check for any undirected cycles ignores the implicit direction of each link. This option uses JGoDocument.makesUndirectedCycle() in the implementation of JGoPort.validLink().

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values

CyclesDestinationTree

public static final int CyclesDestinationTree
A constant value for specifying the cycles allowed in graphs. This value indicates any number of destination links may go out of a port, but at most one source link may come into a port, and there are no directed cycles.

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values

CyclesSourceTree

public static final int CyclesSourceTree
A constant value for specifying the cycles allowed in graphs. This value indicates any number of source links may come into a port, but at most one destination link may go out of a port, and there are no directed cycles.

See Also:
setValidCycle(int), getValidCycle(), Constant Field Values
Constructor Detail

JGoDocument

public JGoDocument()
Construct a new document object.

Method Detail

getDocumentSize

public Dimension getDocumentSize()
Get the document size in document coordinates. This is the virtual extent of all document's objects.

The returned Dimension must not be modified.

Returns:
the document size, in document coordinates

setDocumentSize

public void setDocumentSize(int width,
                            int height)
Set the document size in document coordinates.

Parameters:
width - the new document width
height - the new document height

setDocumentSize

public final void setDocumentSize(Dimension size)
Set the document size in document coordinates.

Parameters:
size - the new document size

updateDocumentSize

protected void updateDocumentSize(JGoObject obj)
Corrects the document size and top-left for an object being added or moved. User programs should never need to call this directly.

Parameters:
obj - the object that may cause a change to the document geometry

getDocumentTopLeft

public org.eclipse.swt.graphics.Point getDocumentTopLeft()
Get the top-left corner of the document, in document coordinates. This is the virtual origin of all document's objects. Normally this will be (0,0), but may include negative X or Y if objects are positioned at negative coordinates.

The returned Point must not be modified.

Returns:
the document top-left corner point, in document coordinates

setDocumentTopLeft

public void setDocumentTopLeft(int x,
                               int y)
Set the document top-left corner in document coordinates.

Parameters:
x - the new left edge of the document
y - the new top edge of the document

setDocumentTopLeft

public final void setDocumentTopLeft(org.eclipse.swt.graphics.Point topleft)
Set the document top-left corner in document coordinates.

Parameters:
topleft - the new document top-left point

computeBounds

public static org.eclipse.swt.graphics.Rectangle computeBounds(JGoObjectSimpleCollection coll)
Determine the smallest rectangle that encloses all of the visible objects in the given collection.


computeBounds

public org.eclipse.swt.graphics.Rectangle computeBounds()
Call computeBounds on the contents of this document.


getPaperColor

public org.eclipse.swt.graphics.RGB getPaperColor()
Gets the background (paper) color.

The default value is null, which permits the JGoView's Background color to determine the apparent color of the background.

Returns:
the color of the background paper.

setPaperColor

public void setPaperColor(org.eclipse.swt.graphics.RGB col)
Sets the background (paper) color.

Parameters:
col - the color of the background paper; a value of null causes the JGoView's Background color to be used instead, by JGoView.paintPaperColor

isModifiable

public boolean isModifiable()
Return whether the user can modify this document interactively. The default value is true.


setModifiable

public void setModifiable(boolean b)
Change whether the user is able to modify this document. This property does not enable or disable any of the document methods for adding or removing objects or for modifying any objects. It is just used by JGoView for enabling the default user behavior for moving or resizing objects, linking ports, and dropping objects. You will still need to enable/disable app commands (actions) and property editors and other features.


getNumObjects

public int getNumObjects()
Returns the number of top-level objects in the document.

Specified by:
getNumObjects in interface JGoObjectSimpleCollection

isEmpty

public boolean isEmpty()
Returns true if the document contains no objects.

Specified by:
isEmpty in interface JGoObjectSimpleCollection

add

public void add(JGoObject obj)
Add an object to the default layer, or to the links layer if the given object is a JGoLink.


addObjectAtHead

public JGoListPosition addObjectAtHead(JGoObject obj)
Adds an object behind all other objects in the document. Returns the position of the object in the list. Objects should not be owned directly by both an Area and a Document, or by more than one document at a time.

Specified by:
addObjectAtHead in interface JGoObjectCollection
Parameters:
obj - the object to add to the document.
Returns:
the position of the new child object.

addObjectAtTail

public JGoListPosition addObjectAtTail(JGoObject obj)
Adds an object in front of all other objects in the document. Returns the position of the object in the list. Objects should not be owned directly by both an Area and a Document, or by more than one document at a time.

Specified by:
addObjectAtTail in interface JGoObjectCollection
Parameters:
obj - the object to add to the document.
Returns:
the position of the new child object.

insertObjectBefore

public JGoListPosition insertObjectBefore(JGoListPosition pos,
                                          JGoObject obj)
Adds an object to the document before the given position. The object will appear behind the object at the given position. Objects should not be owned directly by both an Area and a Document, or by more than one document at a time.

If the object is already a top-level part of this document, the object is moved in the drawing order. The CHANGED document event will have a JGoObject.ChangedZOrder hint/flag and a previous value that is the JGoObject that used to follow the given object in the area.

The object is inserted in the same layer as the given list position.

Specified by:
insertObjectBefore in interface JGoObjectCollection
Parameters:
pos - the position before which to add the object.
obj - the object to add.
Returns:
the position of the new object.

insertObjectAfter

public JGoListPosition insertObjectAfter(JGoListPosition pos,
                                         JGoObject obj)
Adds an object to the document after the given position. The object will appear in front of the object at the given position. Objects should not be owned directly by both an Area and a Document, or by more than one document at a time.

If the object is already a top-level part of this document, the object is moved in the drawing order. The CHANGED document event will have a JGoObject.ChangedZOrder hint/flag and a previous value that is the JGoObject that used to follow the given object in the area.

The object is inserted in the same layer as the given list position.

Specified by:
insertObjectAfter in interface JGoObjectCollection
Parameters:
pos - the position after which to add the object.
obj - the object to add.
Returns:
the position of the new object.

bringObjectToFront

public void bringObjectToFront(JGoObject obj)
Moves an object in front of other objects in the document (moved to the end of the list of objects).

The CHANGED document event will have a JGoObject.ChangedZOrder hint/flag and a previous value that is the JGoObject that used to follow the given object in the area.

The object should already be a part of this document.

Specified by:
bringObjectToFront in interface JGoObjectCollection
Parameters:
obj - the object to move to the front.

sendObjectToBack

public void sendObjectToBack(JGoObject obj)
Moves an object behind other objects in the document (moved to the head of the list of objects).

The CHANGED document event will have a JGoObject.ChangedZOrder hint/flag and a previous value that is the JGoObject that used to follow the given object in the area.

The object should already be a part of this document.

Specified by:
sendObjectToBack in interface JGoObjectCollection
Parameters:
obj - the object to move to the back.

removeObject

public void removeObject(JGoObject obj)
Removes an object from the document.

If the object is not part of this document, this method is a no-op. If the object is a child of a JGoArea instead of being a top-level document object, it is removed from that area.

Specified by:
removeObject in interface JGoObjectCollection
Parameters:
obj - the object to remove.

removeObjectAtPos

public JGoObject removeObjectAtPos(JGoListPosition pos)
Description copied from interface: JGoObjectCollection
Remove an object at specified position from the collection.

Specified by:
removeObjectAtPos in interface JGoObjectCollection
Parameters:
pos - the position of the object to remove.
Returns:
the object removed from the collection.

removeAll

public void removeAll()
Remove all objects from this document without removing any layers.


deleteContents

public void deleteContents()
Removes all the objects and all layers (but the first one) from the document.


pickObject

public JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck,
                            boolean selectableOnly)
Given a point in document coordinates, return the topmost object that contains that point. If selectableOnly is true, only objects that are marked as selectable will be looked at. If no object is found that contains the given point and that meets the selection criteria, null is returned.

Specified by:
pickObject in interface JGoObjectCollection
Parameters:
pointToCheck - the point under which to search, in document coordinates.
selectableOnly - if true, only consider selectable objects.
Returns:
the first object in the collection containing the indicated point.

pickObjects

public java.util.ArrayList pickObjects(org.eclipse.swt.graphics.Point p,
                                       boolean selectableOnly,
                                       java.util.ArrayList coll,
                                       int max)
Return a list of all the JGoObjects that contain a given point.

This calls JGoLayer.pickObjects on each of the layers of this document in reverse order, from front to back. Please note that when objects are found, they might not be a top-level objects. In fact, when "selectableOnly" is false, it is very likely that if any object is found at the given point, it will be a child of some group.

Parameters:
p - a Point in document coordinates
selectableOnly - if true, only consider selectable objects
coll - an ArrayList to which any objects found are added; if null, this method allocates a new ArrayList and returns it
max - a limit on the number of objects that may be returned in the ArrayList
Returns:
the ArrayList of JGoObjects that contain the given point; this is the value of the "coll" parameter if non-null, or else a newly allocated ArrayList

getFirstObjectPos

public JGoListPosition getFirstObjectPos()
Description copied from interface: JGoObjectSimpleCollection
Return the position of the first object in the collection. This will be null if the list is empty.

Specified by:
getFirstObjectPos in interface JGoObjectSimpleCollection

getLastObjectPos

public JGoListPosition getLastObjectPos()
Description copied from interface: JGoObjectCollection
Return the position of the last object in the collection. This will be null if the list is empty.

Specified by:
getLastObjectPos in interface JGoObjectCollection
Returns:
the position of the last object in the collection.

getNextObjectPos

public JGoListPosition getNextObjectPos(JGoListPosition pos)
Return the next object position, recursing into any JGoAreas. Use getNextObjectPosAtTop to only look at top-level objects in the document.

Specified by:
getNextObjectPos in interface JGoObjectSimpleCollection
Parameters:
pos - the current position
Returns:
the next object position

getNextObjectPosAtTop

public JGoListPosition getNextObjectPosAtTop(JGoListPosition pos)
Description copied from interface: JGoObjectSimpleCollection
Return the position for the next top-level object in the collection. A top-level JGoObject is one which is not contained in any JGoArea objects.

Specified by:
getNextObjectPosAtTop in interface JGoObjectSimpleCollection
Parameters:
pos - the position from which to start searching for the next top-level object.
Returns:
an iterator for the next top-level object in the collection; null if there are no more objects.

getPrevObjectPos

public JGoListPosition getPrevObjectPos(JGoListPosition pos)
Description copied from interface: JGoObjectCollection
Return the position of the previous object in the collection.

Specified by:
getPrevObjectPos in interface JGoObjectCollection
Parameters:
pos - the position of the object that follows the object position to be returned.
Returns:
the position of the previous object in the collection; null if there are no more objects.

getObjectAtPos

public JGoObject getObjectAtPos(JGoListPosition pos)
Description copied from interface: JGoObjectSimpleCollection
Return the object for the given position.

Specified by:
getObjectAtPos in interface JGoObjectSimpleCollection
Parameters:
pos - the position of an object in the collection.
Returns:
the object for this position in the collection.

findObject

public JGoListPosition findObject(JGoObject obj)
Description copied from interface: JGoObjectCollection
Return the position of a specific object in the collection.

Specified by:
findObject in interface JGoObjectCollection
Parameters:
obj - the object whose position in the collection is to be returned. to be returned.
Returns:
the position of the indicated object; null if not found.

addDocumentListener

public void addDocumentListener(JGoDocumentListener l)
Add a listener for JGoDocument events.

Parameters:
l - an object supporting the JGoDocumentListener interface

removeDocumentListener

public void removeDocumentListener(JGoDocumentListener l)
Remove a listener for JGoDocument events.

Parameters:
l - an object supporting the JGoDocumentListener interface

getDocumentListeners

public JGoDocumentListener[] getDocumentListeners()
Return an array of the JGoDocumentListeners that are currently listening for JGoDocumentEvents on this document.


fireUpdate

public void fireUpdate(int hint,
                       int flags,
                       java.lang.Object object,
                       int prevInt,
                       java.lang.Object prevObj)
Notify all interested parties of modifications to the JGoDocument. Notification is performed by calling documentChanged() on all registered JGoDocumentListeners.

Caution: when isSuspendUpdates() is true, this method is a no-op.

Parameters:
hint - a value identifying what type of update is occurring. Hint constant values are identified in JGoDocumentEvent and are additionally defined by JGoDocument extensions.
flags - an integer value providing additional sub-hint information
object - an Object associated with the update, or null if there's no specific object for this event
prevInt - the previous integer value for an object's property if specified by the flags sub-hint
prevObj - the previous object value for an object's property if specified by the flags sub-hint

fireForedate

public void fireForedate(int hint,
                         int flags,
                         java.lang.Object obj)
This method should be called to notify all document listeners about an event that is about to happen. Since the purpose is to notify undo/redo managers about a few kinds of changes for which the regular fireUpdate call is unable to provide a previous value after the change has happened, no previous value information is needed here before the change happens--if desired, the listener should remember the previous state explicitly.

This method should be used in a fashion similar to how JGoObject.foredate should be called before a JGoObject change and a JGoDocumentEvent.CHANGED event caused by a call to JGoObject.update.

Caution: when isSuspendUpdates() is true, this method is a no-op.

Parameters:
hint - a value identifying what type of update is occurring. Hint constant values are identified in JGoDocumentEvent. The actual event hint value will be bitwise OR'ed with JGoDocumentEvent.BEFORE_CHANGING.
flags - an integer value providing additional sub-hint information
obj - an Object associated with the update, or null if there's no specific object for this event

update

public final void update()
Cause all views to be updated.

This method observes the SuspendUpdates properties of this document.


isSuspendUpdates

public boolean isSuspendUpdates()
Return whether this document is not automatically updated when it is changed. By default, of course, this value is false.


setSuspendUpdates

public void setSuspendUpdates(boolean bFlag)
Change whether the screen is updated and document listeners are notified in response to any change to the document or to any objects in this document. This method should be used with caution--you should be sure to call setSuspendUpdates(false) soon after making a group of changes to this document.

A call to setSuspendUpdates(false) will update all document listeners.

For undo and redo support, you should define your own document event hints for your specific kinds of document changes. Before calling setSuspendUpdates(true), call fireForedate with the appropriate hint. After your changes, call setSuspendUpdates(false) and then fireUpdate with the same hint.

You can temporarily turn off updating for an individual object by using JGoObject.setSuspendUpdates(). Again, to support undo and redo, be sure to call JGoObject.foredate before suspending, and JGoObject.update after suspending.

Parameters:
bFlag - true if stop notifications, false if resume notifications

isSkipsUndoManager

public boolean isSkipsUndoManager()
Return whether the UndoManager (if any) should stop recording any changes to this document. This is used by JGoUndoManager.skipEvent. By default this value is false.


setSkipsUndoManager

public void setSkipsUndoManager(boolean bFlag)
Control whether the UndoManager records any changes to this document. Changing this transient property does not notify any listeners.


isMaintainsPartID

public boolean isMaintainsPartID()
Return whether this document makes sure each JGoIdentifiablePart gets a unique PartID when it is added to the document.


setMaintainsPartID

public void setMaintainsPartID(boolean bFlag)
Change whether this document assigns a unique PartID to each JGoIdentifiablePart as it is added to the document.

Setting this property to true will also invoke ensureUniquePartID(). Setting it to false will clear the HashMap that findPart uses, but will not modify any JGoIdentifiablePart PartID.


findPart

public JGoIdentifiablePart findPart(int id)
Return the JGoIdentifiablePart in this document with the given PartID, if any.

Parameters:
id - an integer PartID
Returns:
null if there is no such part, or if isMaintainsPartID() is false

ensureUniquePartID

public void ensureUniquePartID()
Make sure all of the objects in this document that implement JGoIdentifiablePart have unique PartID.

This method does nothing if isMaintainsPartID() is false.


copyOldValueForUndo

public void copyOldValueForUndo(JGoDocumentChangedEdit e)
This method is called when a JGoDocumentChangedEdit is created. The previous value Object provided by JGoDocument.fireUpdate or JGoObject.update might be altered by future changes. But losing that state would make it hard for the JGoDocumentChangedEdit to perform an undo correctly. In these cases it is important for the JGoDocumentChangedEdit to make a copy of the Object value, by calling setOldValue with a copy of the getOldValue Object.

The exact nature of the Object depends on the particular event hint or sub-hint, of course, but is typically a Rectangle or Point or some similar structure that is actually owned by the document or object. The responsibility for copying rests with the document event listener rather than the code calling JGoObject.update or JGoDocument.fireUpdate for efficiency when there is no undo/redo manager.

Parameters:
e - the UndoableEdit that also remembers the kind of change and any appropriate previous state that should be copied in-place

copyNewValueForRedo

public void copyNewValueForRedo(JGoDocumentChangedEdit e)
This method is called when a JGoDocumentChangedEdit is created. In order for the JGoDocumentChangedEdit to be able to perform a redo, it needs to remember the new property value or state. However, the JGoDocument.fireUpdate and JGoObject.update methods do not provide such a new value. The value must be taken from the appropriate object and copied into the JGoDocumentChangedEdit by calling setNewValue and/or setNewValueInt.

Just like the previous/old value/state information 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 or JGoDocument.fireUpdate for efficiency when there is no undo/redo manager.

Parameters:
e - the UndoableEdit that also remembers the kind of change and any appropriate new state that should be copied in

changeValue

public void changeValue(JGoDocumentChangedEdit e,
                        boolean undo)
This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the state change.

For JGoDocumentEvent.CHANGED events, the JGoObject's changeValue method is called.

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

Parameters:
e - the UndoableEdit that also remembers the kind of change and any appropriate old and new state for performing an undo or redo
undo - if true, this method should restore the old state/value, otherwise this method should restore the new state/value

createDefaultCopyEnvironment

public JGoCopyEnvironment createDefaultCopyEnvironment()
Return an appropriate copy environment for copying objects to this document. This defaults to a new JGoCopyMap.

See Also:
JGoCopyMap

addCopy

public JGoObject addCopy(JGoObject obj,
                         org.eclipse.swt.graphics.Point loc)
Add a copy of an object into this document at the given point.

This creates a singleton collection and calls copyFromCollection with the appropriate offset. This method is different from addObjectAtTail in that the latter method causes the document to own the object; i.e., the object's layer property is modified to be this document's default layer. But this method does not modify the parameter object and may add the copy to a different layer, if the parameter object belongs to a layer and copyFromCollection can find a matching layer in this document.

If you want to make a copy of a JGoObject but do not want to add it to a document, you can call JGoCopyMap.copyComplete or JGoObject.copy().

Returns:
the newly inserted copied object

copyFromCollection

public JGoCopyEnvironment copyFromCollection(JGoObjectSimpleCollection coll)
Copy the JGoObjects in the given collection into this document. The new objects will have the same size and position as the original objects. A default copy environment is used to control how copying is done.

Parameters:
coll - a simple collection of objects, such as JGoSelection or another JGoDocument
Returns:
the copy environment with the results

copyFromCollection

public JGoCopyEnvironment copyFromCollection(JGoObjectSimpleCollection coll,
                                             org.eclipse.swt.graphics.Point offset,
                                             JGoCopyEnvironment map)
Copy the JGoObjects in the given collection into this document. Move all the new objects by the given offset from their original positions. Use the given copy environment for deciding if and how to copy the objects, and for providing a mapping of the results of the copy that is returned. This will call JGoCopyEnvironment.copy, which will call JGoObject.copyObject to do the actual object copying. This calls JGoObject.computeMove to determine the new Location for each copied object.

A selected object's getDraggingObject() determines what is actually copied. In earlier versions what was copied was always the selected object's top-level object. Because by default JGoObject.getDraggingObject() normally returns JGoObject.getTopLevelObject(), the behavior is compatible, but now there is the possibility to copy parts of areas without copying the whole area. (The same is true for moving, as defined by JGoView.moveSelection.)

If the collection of objects is from this same document, each copied object is added to the original object's layer. If the original object comes from a different document, the new object is added to a layer with the same identifier as the original object's layer. If no such layer is found, the default layer is used to hold the new object.

Parameters:
coll - a simple collection of objects, such as JGoSelection or another JGoDocument
offset - specify the (x,y) by which all copied objects should be moved
map - a copy environment to control the copying and hold the results; if this is null, the result of createDefaultCopyEnvironment() is used.
Returns:
the copy environment with the results

getNumLayers

public int getNumLayers()
Return the number of layers in this document. This number is initially one, and should never be less than one.


getFirstLayer

public JGoLayer getFirstLayer()
Return the bottom-most layer of objects in this document.


getLastLayer

public JGoLayer getLastLayer()
Return the top-most layer of objects in this document.


getNextLayer

public JGoLayer getNextLayer(JGoLayer layer)
Return the layer just above the given layer. Return null if the given layer is the top-most one.


getPrevLayer

public JGoLayer getPrevLayer(JGoLayer layer)
Return the layer just below the given layer. Return null if the given layer is the bottom-most one.


getDefaultLayer

public JGoLayer getDefaultLayer()
Return the default layer for creating new objects by methods that do not explicitly state which layer to use. For example, this layer is used by copyFromCollection and JGoView.newLink. By default this is the initially created layer for this document.


setDefaultLayer

public void setDefaultLayer(JGoLayer layer)
Change the default layer used to hold newly created objects created by copyFromCollection (and thus by JGoView.paste). The layer must belong to this document.


getLinksLayer

public JGoLayer getLinksLayer()
Return the layer that by convention holds links. By default this is initially the same as getDefaultLayer(), since initially a document only has one layer.


setLinksLayer

public void setLinksLayer(JGoLayer layer)
Change the layer to be used by convention to hold links. The layer must belong to this document.


addLayerAfter

public JGoLayer addLayerAfter(JGoLayer old)
Create a new empty layer and add it to this document just in front of the given layer.

Parameters:
old - an existing layer of this document that should be just behind the new one
Returns:
the new layer

addLayerBefore

public JGoLayer addLayerBefore(JGoLayer old)
Create a new empty layer and add it to this document just behind the given layer.

Parameters:
old - an existing layer of this document that should be just in front of the new one
Returns:
the new layer

removeLayer

public void removeLayer(JGoLayer layer)
Remove all of the given layer's objects from this document, and then remove the layer itself from this document.

You cannot remove the only layer left in a document if there is only one.


insertLayerAfter

public void insertLayerAfter(JGoLayer old,
                             JGoLayer insert)
Re-order the layers of this document by moving a layer in front of another one.

Parameters:
old - the existing layer that will be occluded
insert - the existing layer to be moved

insertLayerBefore

public void insertLayerBefore(JGoLayer old,
                              JGoLayer insert)
Re-order the layers of this document by moving a layer behind another one.

Parameters:
old - the existing layer that will be just in front of the moved layer
insert - the existing layer to be moved

bringLayerToFront

public void bringLayerToFront(JGoLayer layer)
Re-order the layers of this document by moving the given one in front of all of the others.


sendLayerToBack

public void sendLayerToBack(JGoLayer layer)
Re-order the layers of this document by moving the given one behind all of the others.


findLayer

public JGoLayer findLayer(java.lang.Object identifier)
Return a layer whose identifier equals the given identifier argument.

If the given identifier is null, this method returns null. If a layer has no identifier, it will not match the argument identifier. If more than one layer has an identifier that equals the argument identifier, any one of those layers may be returned.

Parameters:
identifier - any Object, but normally a String or Integer
Returns:
a layer that matches the identifier, or null if there is none

sortByZOrder

public void sortByZOrder(JGoObject[] a)
Sort an Array of JGoObjects by their Z-order position in the layers of this document.

This method does not modify the order of any objects in any layer--it simply modifies the argument array by sorting the objects by their current Z-order in these layers. For example, if you have a few selected objects, you can use this method to find the selected object which is in front of the other selected objects. That would be the last object in the array after calling this method.

If one or more elements of the argument array are not JGoObjects that belong to one of these layers, the resulting sort order is indeterminate.

Parameters:
a - a JGoObject[] array that is modified according to object Z-order

getUndoManager

public JGoUndoManager getUndoManager()
Return the JGoUndoManager that is responsible for tracking all changes to this document. By default there is no undo manager, so this will return null.


setUndoManager

public void setUndoManager(JGoUndoManager m)
Specify the JGoUndoManager that should be responsible for tracking all changes to this document and all of its objects. Providing a non-null value will turn on undo/redo functionality.

Setting this property does not notify any listeners about the fact that this property changed.

Parameters:
m - the new UndoManager, or null if an UndoManager is no longer desired

canUndo

public boolean canUndo()
This predicate is delegated to the document's UndoManager, if any.


undo

public void undo()
This method is delegated to the document's UndoManager, if any.

In addition, all document listeners are updated, first beforehand with a hint of JGoDocumentEvent.STARTING_UNDO, and then afterwards with a hint of JGoDocumentEvent.FINISHED_UNDO.


canRedo

public boolean canRedo()
This predicate is delegated to the document's UndoManager, if any.


redo

public void redo()
This method is delegated to the document's UndoManager, if any.

In addition, all document listeners are updated, first beforehand with a hint of JGoDocumentEvent.STARTING_REDO, and then afterwards with a hint of JGoDocumentEvent.FINISHED_REDO.


startTransaction

public void startTransaction()
This method is delegated to the document's UndoManager, if any.

This method is called in a few situations by JGoView. Other code that makes changes to a document or its objects should also call this method before any of the changes have been performed.

If this starts a top-level (unnested) transaction, this notifies all document listeners with a hint of JGoDocumentEvent.STARTED_TRANSACTION.


endTransaction

public void endTransaction(boolean commit)
This method is delegated to the document's UndoManager, if any. This method is called in a few situations by JGoView. Other code that makes changes to a document or its objects should also call this method after all of the changes have been performed.

Note that calling endTransaction(false) does not actually undo any or all of the changes that have happened since the last call to startTransaction. Instead, only the record of those changes will be thrown away. This behavior is reasonable for the normal case because JGoView has to restore the "before" state even if no undo/redo functionality is present.

If this ends a top-level (unnested) transaction, this notifies all document listeners with a hint of JGoDocumentEvent.FINISHED_TRANSACTION if commit is true, or a hint of JGoDocumentEvent.ABORTED_TRANSACTION if commit is false.

Parameters:
commit - true for normal edits, false for aborting all of the edits that have occurred since the last transaction

endTransaction

public void endTransaction(java.lang.String pname)
This method is delegated to the document's UndoManager, if any. This method is called in a few situations by JGoView. Other code that makes changes to a document or its objects should also call this method after all of the changes have been performed.

Unlike endTransaction(boolean), this method assumes the transaction is being committed, and furthermore gives it a presentation name.

If this ends a top-level (unnested) transaction, this notifies all document listeners with a hint of JGoDocumentEvent.FINISHED_TRANSACTION.

Parameters:
pname - the presentation name for the ongoing CompoundEdit being ended

discardAllEdits

public void discardAllEdits()
This method is delegated to the document's UndoManager, if any. Typically an application will call this method after saving the document, when it does not wish to hang on to all of the undo/redo memory.


isAvoidable

public boolean isAvoidable(JGoObject obj)
This predicate determines whether the search for a route for a link whose isAvoidsNodes() property is true will try to go around the given object. By default, this is true for all JGoNodes and false otherwise.

Parameters:
obj - a top-level object in the document that the router may need to consider

getAvoidableRectangle

public org.eclipse.swt.graphics.Rectangle getAvoidableRectangle(JGoObject obj,
                                                                org.eclipse.swt.graphics.Rectangle rect)
For an object that is assumed to be isAvoidable(), return the rectangle that the object should occupy.

By default, this returns the bounding rectangle of the object. The rectangle is expanded by JGoObject.expandRectByPenWidth() to account for any extended appearance.

Parameters:
obj - the object for which this method determines the effective size and location for routing links whose JGoLink.isAvoidsNodes() property is true.
rect - a Rectangle that is modified and returned; if null, a new Rectangle is allocated

isUnoccupied

public boolean isUnoccupied(org.eclipse.swt.graphics.Rectangle r,
                            JGoObject skip)
Returns true if there are any "avoidable" objects within or intersecting the given rectangular region.

This only considers document objects for which isAvoidable returns true, with the "occupied" space determined by getAvoidableRectangle.

Parameters:
r - a Rectangle in document coordinates
skip - an object that should be ignored when checking for collisions, usually the object in the document that you are considering moving; may be null to consider all avoidable objects

setValidCycle

public void setValidCycle(int validCycle)
Sets whether a valid link can be made between two ports that may produce a directed or undirected cycle in this document. JGoPort.validLink uses this property in the following manners:

JGoDocument.CyclesAllowAll produces no checking for cycles.

JGoDocument.CyclesNotDirected checks for possible cycle consisting of directed links. This check is slower and consumes more memory than the "Fast" version, but will not fail even if there are cycles or loops in the graph.

JGoDocument.CyclesNotDirectedFast checks for possible cycle consisting of directed links, without concern for any existing directed cycles elsewhere in the graph. Thus using this mode may result in infinite recursion and stack overflows if there happen to be any directed cycles accessible from either port in a call to JGoPort.validLink().

JGoDocument.CyclesNotUndirected checks for possible cycle consisting of links in either direction.

JGoDocument.CyclesDestinationTree checks for possible links that would cause the graph no longer to be a tree, with each node having at most one source link.

JGoDocument.CyclesSourceTree checks for possible links that would cause the graph no longer to be a tree, with each node having at most one destination link.

Parameters:
validCycle - This defaults to JGoDocument.CyclesAllowAll, resulting in no checks for a new link possibly producing any kind of cycle or loop.

getValidCycle

public int getValidCycle()
Gets whether a valid link can be made between two ports that may produce a directed or undirected cycle in this document.

Returns:
a Cycles... constant determining the kind of cycle checking currently in use.
See Also:
setValidCycle(int)

makesDirectedCycleFast

public static boolean makesDirectedCycleFast(JGoNode a,
                                             JGoNode b)
This method returns true if adding a link from a to b would result in a cycle of directed links going through the node a. This method ignores any reflexive links--i.e. links whose ports are both part of the same node. This assumes that there are no directed cycles already present in the graph. If there are any such cycles, this recursive method may cause stack overflows or infinite recursion. However, this method is faster than makesDirectedCycle(). Set ValidCycle to JGoDocument.CyclesNotDirectedFast when you can be sure there are never any cycles in the graph; otherwise set it to JGoDocument.ValidCycleCyclesNotDirected, which is slower but can handle existing cycles in the graph.

Parameters:
a - the node to start from
b - the node that the proposed link would connect to
Returns:
true if adding the link would create a directed cycle. false otherwise.
See Also:
getValidCycle(), makesDirectedCycle(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), makesUndirectedCycle(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), JGoPort.validLink(com.nwoods.jgo.JGoPort)

makesDirectedCycle

public static boolean makesDirectedCycle(JGoNode a,
                                         JGoNode b)
This method returns true if adding a link from a to b would result in a cycle of directed links going through the node a. This method ignores any reflexive links--i.e. links whose ports are both part of the same node.

Parameters:
a - the node to start from
b - the node that the proposed link would connect to
Returns:
true if adding the link would create a directed cycle. false otherwise.
See Also:
setValidCycle(int), makesDirectedCycleFast(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), makesUndirectedCycle(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), JGoPort.validLink(com.nwoods.jgo.JGoPort)

makesUndirectedCycle

public static boolean makesUndirectedCycle(JGoNode a,
                                           JGoNode b)
This method returns true if adding a link from a to b would result in a cycle or loop of links, regardless of link direction, going through the node a. This method ignores any reflexive links--i.e. links whose ports are both part of the same node.

Parameters:
a - the node to start from
b - the node that the proposed link would connect to
Returns:
true if adding the link would create an undirected cycle. false otherwise.
See Also:
setValidCycle(int), makesDirectedCycle(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), makesDirectedCycleFast(com.nwoods.jgo.JGoNode, com.nwoods.jgo.JGoNode), JGoPort.validLink(com.nwoods.jgo.JGoPort)

SVGWriteObject

public void SVGWriteObject(DomDoc svgDoc,
                           DomElement jGoElementGroup)
Write a DomElement containing the JGoDocument properties out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGWriteDoc(). Refer to com.nwoods.jgo.JGoObject.SVGWriteObject for more details.

Specified by:
SVGWriteObject in interface JGoXMLSaveRestore
Parameters:
svgDoc - the DomDoc in which to construct the SVG representation of this object
jGoElementGroup - the DomElement to which to attach this object
See Also:
JGoObject.SVGWriteObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.DomElement), JGoObject.SVGReadObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.JGoDocument, com.nwoods.jgo.DomElement, com.nwoods.jgo.DomElement), DomDoc, DomNode, DomElement, DomText

SVGReadObject

public DomNode SVGReadObject(DomDoc svgDoc,
                             JGoDocument jGoDoc,
                             DomElement svgElement,
                             DomElement jGoChildElement)
Read a DomElement containing the JGoDocument properties from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.

This method will be called by com.nwoods.jgo.svg.DefaultDocument.SVGReadDoc(). Refer to com.nwoods.jgo.JGoObject.SVGReadObject for more details.

Specified by:
SVGReadObject in interface JGoXMLSaveRestore
Parameters:
svgDoc - the DomDoc containing the SVG representation of this object
jGoDoc - the JGoDocument in which this object was created
svgElement - the element being read (typically the <g> element containing the JGoObject definition)
jGoChildElement - the current <JGoClass> element being read withing the <g>
See Also:
JGoObject.SVGWriteObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.DomElement), JGoObject.SVGReadObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.JGoDocument, com.nwoods.jgo.DomElement, com.nwoods.jgo.DomElement), DomDoc, DomNode, DomElement, DomText

SVGUpdateReference

public void SVGUpdateReference(java.lang.String attr,
                               java.lang.Object referencedObject)

SVGWriteLayer

public void SVGWriteLayer(DomDoc svgDoc,
                          DomElement jGoElementGroup,
                          JGoLayer layer)
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.

Parameters:
svgDoc - the DomDoc in which to construct the SVG representation of this object
jGoElementGroup - the DomElement to which to attach this object (layer)
layer - the layer being written
See Also:
JGoObject.SVGReadObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.JGoDocument, com.nwoods.jgo.DomElement, com.nwoods.jgo.DomElement), JGoObject.SVGWriteAttributes(com.nwoods.jgo.DomElement), JGoObject.SVGReadAttributes(com.nwoods.jgo.DomElement), JGoObject.SVGUpdateReference(java.lang.String, java.lang.Object), DomDoc, DomNode, DomElement, DomText

SVGReadLayer

public DomNode SVGReadLayer(DomDoc svgDoc,
                            JGoDocument jGoDoc,
                            DomElement svgElement,
                            DomElement jGoChildElement,
                            JGoLayer layer)
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.

Parameters:
svgDoc - the DomDoc containing the SVG representation of this object
jGoDoc - the JGoDocument in which this object was created
svgElement - the element being read (typically the <g> element containing the JGoObject definition)
jGoChildElement - the current <JGoClass> element being read withing the <g>
See Also:
JGoObject.SVGWriteObject(com.nwoods.jgo.DomDoc, com.nwoods.jgo.DomElement), JGoObject.SVGWriteAttributes(com.nwoods.jgo.DomElement), JGoObject.SVGReadAttributes(com.nwoods.jgo.DomElement), JGoObject.SVGUpdateReference(java.lang.String, java.lang.Object), DomDoc, DomNode, DomElement, DomText