Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.nwoods.jgo
Class JGoDocument

    java.lang.Object
      com.nwoods.jgo.JGoDocument

All Implemented Interfaces:
  JGoObjectCollection, JGoObjectSimpleCollection, JGoXMLSaveRestore, java.io.Serializable, java.awt.datatransfer.Transferable

public class JGoDocument
extends java.lang.Object
implements JGoObjectCollection, java.awt.datatransfer.Transferable, 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 Transferable and provides a default DataFlavor. 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, java.awt.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.
`java.awt.Rectangle` | `computeBounds()` Call computeBounds on the contents of this document.
`static java.awt.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, java.awt.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.
`java.awt.Rectangle` | `getAvoidableRectangle(JGoObject obj, java.awt.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.
`java.awt.Dimension` | `getDocumentSize()` Get the document size in document coordinates.
`java.awt.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.
`java.awt.Color` | `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.
`static java.awt.datatransfer.DataFlavor` | `getStandardDataFlavor()` Provide a single standard DataFlavor supporting JGo objects.
`java.lang.Object` | `getTransferData(java.awt.datatransfer.DataFlavor f)` This method implements Transferable, using getStandardDataFlavor().
`java.awt.datatransfer.DataFlavor[]` | `getTransferDataFlavors()` This method implements Transferable, using getStandardDataFlavor().
`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` | `isDataFlavorSupported(java.awt.datatransfer.DataFlavor f)` This method implements Transferable, using getStandardDataFlavor().
`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(java.awt.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(java.awt.Point pointToCheck, boolean selectableOnly)` Given a point in document coordinates, return the topmost object that contains that point.
`java.util.ArrayList` | `pickObjects(java.awt.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(java.awt.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(java.awt.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(java.awt.Color 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 java.awt.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(java.awt.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 java.awt.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(java.awt.Point topleft)

  Set the document top-left corner in document coordinates.

  Parameters:
    `topleft` - the new document top-left point

### computeBounds

    public static java.awt.Rectangle computeBounds(JGoObjectSimpleCollection coll)

  Determine the smallest rectangle that encloses all of the visible objects in the given collection.

### computeBounds

    public java.awt.Rectangle computeBounds()

  Call computeBounds on the contents of this document.

### getPaperColor

    public java.awt.Color 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(java.awt.Color 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(java.awt.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(java.awt.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

### getStandardDataFlavor

    public static java.awt.datatransfer.DataFlavor getStandardDataFlavor()

  Provide a single standard DataFlavor supporting JGo objects.

### getTransferDataFlavors

    public java.awt.datatransfer.DataFlavor[] getTransferDataFlavors()

  This method implements Transferable, using getStandardDataFlavor().

  Specified by:
    `getTransferDataFlavors` in interface `java.awt.datatransfer.Transferable`

### isDataFlavorSupported

    public boolean isDataFlavorSupported(java.awt.datatransfer.DataFlavor f)

  This method implements Transferable, using getStandardDataFlavor().

  Specified by:
    `isDataFlavorSupported` in interface `java.awt.datatransfer.Transferable`

### getTransferData

    public java.lang.Object getTransferData(java.awt.datatransfer.DataFlavor f)
                                     throws java.awt.datatransfer.UnsupportedFlavorException,
                                            java.io.IOException

  This method implements Transferable, using getStandardDataFlavor().

  Specified by:
    `getTransferData` in interface `java.awt.datatransfer.Transferable`
  Throws:
    `java.awt.datatransfer.UnsupportedFlavorException`
    `java.io.IOException`

### 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,
                             java.awt.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,
                                                 java.awt.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 java.awt.Rectangle getAvoidableRectangle(JGoObject obj,
                                                    java.awt.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(java.awt.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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD