com.nwoods.jgo
Class JGoArea

java.lang.Object
  extended bycom.nwoods.jgo.JGoObject
      extended bycom.nwoods.jgo.JGoArea
All Implemented Interfaces:
JGoObjectCollection, JGoObjectSimpleCollection, JGoXMLSaveRestore, java.io.Serializable
Direct Known Subclasses:
JGoNode

public class JGoArea
extends JGoObject
implements JGoObjectCollection

JGoArea implements the concept of a "group" of objects that can be manipulated together. An area, like a document, contains a list of JGoObjects. These objects must not also be contained directly by the document, or by other areas.

Most "nodes" of a graph are implemented by extending from the JGoNode class, or one of the predefined nodes classes such as JGoBasicNode, JGoIconicNode, or JGoTextNode.

JGoArea is a subclass of JGoObject, which means that areas can contain other areas. This is the Composite pattern. Using this mechanism, an object hierarchy can be created.

An area does not really have its own independent bounding rectangle. Instead the bounding rectangle is really the bounding rectangle for all of the children. In fact getBoundingRect() is not meaningful when there are no objects in an area.

JGoDocument and JGoView treat areas specially--they search in them when you use pickObject() or getNextObject().

A selectable area will get selected when the user clicks on a child that is not selectable. Clicking on a part of the area where there is no child will not select this area unless you first call setPickableBackground(true).

See Also:
JGoNode, JGoDocument, JGoView, JGoObjectCollection, Serialized Form

Field Summary
static int ChangedPickableBackground
          a CHANGED JGoDocumentEvent subhint: changed whether the user can pick this subgraph not at a child
 
Fields inherited from class com.nwoods.jgo.JGoObject
Bottom, BottomCenter, BottomLeft, BottomMiddle, BottomRight, Center, CenterLeft, CenterRight, Changed4ResizeHandles, ChangedAutoRescale, ChangedBrush, ChangedDraggable, ChangedDragsNode, ChangedGeometry, ChangedGrabChildSelection, ChangedInitializing, ChangedPen, ChangedResizable, ChangedSelectable, ChangedUpdatePartner, ChangedVisible, ChangedZOrder, LastChangedHint, Left, LeftCenter, NoHandle, NoSpot, NumReservedHandles, RepaintAll, Right, RightCenter, SideLeft, SideRight, Top, TopCenter, TopLeft, TopMiddle, TopRight
 
Constructor Summary
JGoArea()
          Construct a new empty JGoArea.
 
Method Summary
 java.util.ArrayList addCollection(java.util.ArrayList coll, boolean reparentLinks, JGoLayer linksLayer)
          Move some objects into this area, as immediate children of this group, even if they are part of other areas in this same layer.
 java.util.ArrayList addCollection(JGoObjectSimpleCollection coll, boolean reparentLinks, JGoLayer linksLayer)
          Move some objects into this area, as immediate children of this group, even if they are part of other areas in this same layer.
 JGoListPosition addObjectAtHead(JGoObject obj)
          Adds a child to the beginning of this area's list of children, appearing underneath other objects in this area.
 JGoListPosition addObjectAtTail(JGoObject obj)
          Adds a child to the end of this area's list of children, appearing on top of other objects in this area.
 void bringObjectToFront(JGoObject obj)
          Moves a child object of this area to the "front" of the z-order.
 void changeValue(JGoDocumentChangedEdit e, boolean undo)
          This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the property value change for a JGoObject.
protected  org.eclipse.swt.graphics.Rectangle computeBoundingRect()
          Recalculate the correct bounding box for this area by going through all of its children.
protected  void copyChildren(JGoArea newarea, JGoCopyEnvironment env)
          The default implementation for copying child objects is to just add a copy of each child to the new area.
 void copyNewValueForRedo(JGoDocumentChangedEdit e)
          This method is called when a JGoDocumentChangedEdit is created for a JGoDocumentEvent.CHANGED event, when a JGoObject has been changed.
 JGoObject copyObject(JGoCopyEnvironment env)
          Create a new instance of this object with the same field values.
 void expandRectByPenWidth(org.eclipse.swt.graphics.Rectangle rect)
          Account for the pen widths of the area's children.
 JGoListPosition findObject(JGoObject obj)
          Return the position of a specific object in the collection.
protected  void geometryChange(org.eclipse.swt.graphics.Rectangle prevRect)
          Called when the geometry (size or position) of this area is changed.
protected  boolean geometryChangeChild(JGoObject child, org.eclipse.swt.graphics.Rectangle prevRect)
          Call layoutChildren because one of the children of this JGoArea has been moved or resized.
 JGoListPosition getFirstObjectPos()
          Return the position of the first object in the collection.
 JGoListPosition getLastObjectPos()
          Return the position of the last object in the collection.
 boolean getNearestIntersectionPoint(int px, int py, int cx, int cy, org.eclipse.swt.graphics.Point result)
          A group's closest intersection point with a line is the closest such point among all of the children.
 JGoListPosition getNextObjectPos(JGoListPosition pos)
          Return the position for the next object in the collection.
 JGoListPosition getNextObjectPosAtTop(JGoListPosition pos)
          Return the position for the next top-level object in the collection.
 int getNumObjects()
          Return the number of top-level objects in the collection.
 JGoObject getObjectAtPos(JGoListPosition pos)
          Return the object for the given position.
 JGoListPosition getPrevObjectPos(JGoListPosition pos)
          Return the position of the previous object in the collection.
 JGoListPosition insertObjectAfter(JGoListPosition pos, JGoObject obj)
          Adds a child to this area after the given position.
 JGoListPosition insertObjectBefore(JGoListPosition pos, JGoObject obj)
          Adds a child to this area before the given position.
 boolean isEmpty()
          Return true if there are no objects in the collection.
 boolean isPickableBackground()
          Return whether the user can also select this area (if isSelectable() is true) by clicking somewhere within the area but not on any child object.
 void layoutChildren(JGoObject childchanged)
          This method is responsible for repositioning and resizing all of the children.
protected  void moveChildren(org.eclipse.swt.graphics.Rectangle prevRect)
          This method is called by geometryChange when this area's position but not its size has been changed by a call to setBoundingRect.
 void paint(Graphics2D g, JGoView view)
          Draw the area and all its children.
 JGoObject pick(org.eclipse.swt.graphics.Point p, boolean selectableOnly)
          Picking in an area first tries to pick a child object, starting with the last one, which is most in front.
 JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck, boolean selectableOnly)
          Returns the topmost object that is under the given 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 removeObject(JGoObject obj)
          Removes a child object from this area.
 JGoObject removeObjectAtPos(JGoListPosition pos)
          Remove an object at specified position from the collection.
protected  void rescaleChildren(org.eclipse.swt.graphics.Rectangle prevRect)
          This method is called by geometryChange when this area's size has been changed by a call to setBoundingRect.
 void sendObjectToBack(JGoObject obj)
          Moves a child object of this area to the "back" of the z-order.
 void setPickableBackground(boolean bFlag)
          Change whether the user can select this selectable area by clicking somewhere within the subgraph but not on any child object.
 DomNode SVGReadObject(DomDoc svgDoc, JGoDocument jGoDoc, DomElement svgElement, DomElement jGoChildElement)
          Read this object in from a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 void SVGWriteObject(DomDoc svgDoc, DomElement jGoElementGroup)
          Write this object out to a DomDoc representing a Scalable Vector Graphics (SVG) XML document.
 
Methods inherited from class com.nwoods.jgo.JGoObject
canView, computeMove, computeResize, copy, copyObjectDelayed, copyOldValueForUndo, copyRect, doMouseClick, doMouseDblClick, doUncapturedMouseMove, findCommonParent, foredate, gainedSelection, getBoundingRect, getDocument, getDraggingObject, getFlags, getHeight, getLayer, getLeft, getLocation, getLocation, getParent, getParentJGoNode, getParentNode, getPartner, getRectangleSpotLocation, getSize, getSize, getSpotLocation, getSpotLocation, getToolTipText, getTop, getTopLeft, getTopLeft, getTopLevelObject, getView, getWidth, growRect, handleMove, handleResize, hideSelectionHandles, is4ResizeHandles, isAutoRescale, isBoundingRectInvalid, isChildOf, isDraggable, isDragsNode, isInitializing, isPointInObj, isResizable, isSelectable, isSkipsUndoManager, isSuspendUpdates, isTopLevel, isUpdatePartner, isVisible, lostSelection, ownerChange, partnerUpdate, redirectSelection, remove, set4ResizeHandles, setAutoRescale, setBoundingRect, setBoundingRect, setBoundingRect, setBoundingRectInvalid, setBoundsRect, setDraggable, setDragsNode, setFlags, setHeight, setInitializing, setLeft, setLocation, setLocation, setLocationOffset, setLocationOffset, setParent, setPartner, setRectangleSpotLocation, setResizable, setSelectable, setSize, setSize, setSizeKeepingLocation, setSkipsUndoManager, setSpotLocation, setSpotLocation, setSpotLocation, setSpotLocationOffset, setSuspendUpdates, setTop, setTopLeft, setTopLeft, setUpdatePartner, setVisible, setWidth, showSelectionHandles, spotOpposite, SVGReadAttributes, SVGUpdateReference, SVGWriteAttributes, update, update
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ChangedPickableBackground

public static final int ChangedPickableBackground
a CHANGED JGoDocumentEvent subhint: changed whether the user can pick this subgraph not at a child

See Also:
Constant Field Values
Constructor Detail

JGoArea

public JGoArea()
Construct a new empty JGoArea. When created, the bounding rectangle of JGoAreas is null. As soon as any children are added, the bounding rectangle is expanded to enclose those children. As more children are added, removed, and moved, the bounding rectangle is adjusted automatically.

Method Detail

copyObject

public JGoObject copyObject(JGoCopyEnvironment env)
Create a new instance of this object with the same field values. This calls copyChildren() to create instances of the JGoObjects that are in this JGoArea.

Remember that JGoObject.copyObject will return null if the object has already been copied. We suggest using JGoCopyEnvironment.copy instead: newobj.myObjRef = env.copy(myObjRef);

If you override copyChildren for your area class, you may find it more convenient to copy the fields first in that method, rather than also overriding this method. Sometimes the new field values are needed while you are copying child objects, but your override of copyObject will be called after your override of copyChildren.

Overrides:
copyObject in class JGoObject
Parameters:
env - the environment for the copy operation - keeps track of copied objects.
Returns:
a newly allocated copy of this object, or null

copyChildren

protected void copyChildren(JGoArea newarea,
                            JGoCopyEnvironment env)
The default implementation for copying child objects is to just add a copy of each child to the new area.

You may wish to override this in order to keep track of the children or do other bookkeeping. Remember that JGoObject.copyObject will return null if the object has already been copied. We suggest using JGoCopyEnvironment.copy instead: newobj.myObjRef = env.copy(myObjRef);

Or call super.copyChildren first and just refer to the copied objects that are remembered in the copy environment: newobj.myObjRef = (JGoObject)env.get(myObjRef);

Parameters:
newarea - the area newly created by copyObject() to which we need to add copies of the children of this area
env - the environment for the copy operation - keeps track of copied objects.

setPickableBackground

public void setPickableBackground(boolean bFlag)
Change whether the user can select this selectable area by clicking somewhere within the subgraph but not on any child object.

Note that clicking on an unselectable child object will cause this area to be selected, if this area isSelectable().


isPickableBackground

public boolean isPickableBackground()
Return whether the user can also select this area (if isSelectable() is true) by clicking somewhere within the area but not on any child object.

The default value is false, which causes parts of areas where there are no child to act "transparently" with respect to picking.


pick

public JGoObject pick(org.eclipse.swt.graphics.Point p,
                      boolean selectableOnly)
Picking in an area first tries to pick a child object, starting with the last one, which is most in front.

If isVisible() is false for this area, this method returns null. This method calls pickObject to recursively search for a child object that can be picked. If pickObject does not return an object, then this will return null, unless isPickableBackground() is true. If isPickableBackground() is true and no child pick succeeded, then the point is in the background of this area, so this area is returned if selectableOnly is false, or if isSelectable() is true. If neither case holds for this area, then this will search up the Parent chain to find a parent area that isSelectable().

Overrides:
pick in class JGoObject
Parameters:
p - a Point in document coordinates
selectableOnly - whether the return value must be selectable by the user.
Returns:
an object at the given point

pickObject

public JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck,
                            boolean selectableOnly)
Returns the topmost object that is under the given point. If selectableOnly is true, only objects that are selectable are considered. If the point is in an area (in this case, a subarea) that area is searched for an object recursively. If no child is found at the given point, then the method returns null. This method calls JGoObject.pick to let each object decide if the given point is inside the object and visible and other considerations.

Specified by:
pickObject in interface JGoObjectCollection
Parameters:
pointToCheck - the point under which to find an object.
selectableOnly - if true, only include selectable objects in the search.
Returns:
the object under the point if any, this otherwise.

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.

For an area, this is implemented to add the object found by a call to pickObject, if any object is found. Thus for a typical node that happens to have several objects underneath each other, only the top-most (front-most) object is added. Since most child objects are not selectable, if "selectableOnly" is true, this method will typically add the area itself to the result ArrayList collection.

However, this method is overridden on JGoSubGraphBase to have a different behavior.

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

getNearestIntersectionPoint

public boolean getNearestIntersectionPoint(int px,
                                           int py,
                                           int cx,
                                           int cy,
                                           org.eclipse.swt.graphics.Point result)
A group's closest intersection point with a line is the closest such point among all of the children.

Currently, this means that a point on a child object that does not intersect the line from (px,py) to (cx,cy) may be closer than a point on some other child that actually does intersect the line.

Overrides:
getNearestIntersectionPoint in class JGoObject
Parameters:
px - the X coordinate of a point that starts a line
py - the Y coordinate of a point that starts a line
cx - the X coordinate of a point that specifies the other end of the line
cy - the Y coordinate of a point that specifies the other end of the line
result - a Point that is modified (must not be null)
Returns:
whether the line from (px,py) to (cx,cy) intersects the bounding rectangle

SVGWriteObject

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

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

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

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

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

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

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

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

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

SVGReadObject

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

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

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

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

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

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

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

paint

public void paint(Graphics2D g,
                  JGoView view)
Draw the area and all its children. By default, the area has no appearance of its own.

Overrides:
paint in class JGoObject
Parameters:
g - the graphics context on which to draw this area.
view - the view we're drawing in

expandRectByPenWidth

public void expandRectByPenWidth(org.eclipse.swt.graphics.Rectangle rect)
Account for the pen widths of the area's children.

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

computeBoundingRect

protected org.eclipse.swt.graphics.Rectangle computeBoundingRect()
Recalculate the correct bounding box for this area by going through all of its children. The result is guaranteed to be the correct bounding box, but it might take a while to figure it out -- try to call this method as little as possible.

Overrides:
computeBoundingRect in class JGoObject

geometryChange

protected void geometryChange(org.eclipse.swt.graphics.Rectangle prevRect)
Called when the geometry (size or position) of this area is changed.

By default this method handles both moving the area (and all its children) and/or scaling all the children proportional to any changes in the width and height of the new bounding rectangle.

When the size of the area changes, the default rescaling behavior is often inadequate, so this method also calls layoutChildren with a null argument. Override layoutChildren to reposition and resize the children objects in the desired manner.

Overrides:
geometryChange in class JGoObject
Parameters:
prevRect - the previous bounding rectangle of this area.
See Also:
moveChildren(org.eclipse.swt.graphics.Rectangle), rescaleChildren(org.eclipse.swt.graphics.Rectangle), layoutChildren(com.nwoods.jgo.JGoObject)

geometryChangeChild

protected boolean geometryChangeChild(JGoObject child,
                                      org.eclipse.swt.graphics.Rectangle prevRect)
Call layoutChildren because one of the children of this JGoArea has been moved or resized.

Overrides:
geometryChangeChild in class JGoObject
Parameters:
child - the child that has changed
prevRect - the child's previous bounding rectangle
Returns:
true if the bounding rect was changed by this method
See Also:
layoutChildren(com.nwoods.jgo.JGoObject)

moveChildren

protected void moveChildren(org.eclipse.swt.graphics.Rectangle prevRect)
This method is called by geometryChange when this area's position but not its size has been changed by a call to setBoundingRect.

By default, this just moves all this area's child objects by the same offset as the whole area was. All links are moved before any other kind of child. This method is rarely overridden.

Parameters:
prevRect - the original bounds of this area
See Also:
geometryChange(org.eclipse.swt.graphics.Rectangle)

rescaleChildren

protected void rescaleChildren(org.eclipse.swt.graphics.Rectangle prevRect)
This method is called by geometryChange when this area's size has been changed by a call to setBoundingRect.

By default, this just resizes all of this area's child objects by the proportion each child object takes of the whole area. Children whose JGoObject.isAutoRescale() method returns false are not resized or repositioned. All links are moved and resized before any other kind of child. This method is rarely overridden.

Parameters:
prevRect - the original bounds of this area
See Also:
geometryChange(org.eclipse.swt.graphics.Rectangle)

layoutChildren

public void layoutChildren(JGoObject childchanged)
This method is responsible for repositioning and resizing all of the children.

Each node subclass should override this method to position and size each child so that the node has the desired arrangement and appearance. This method is normally called by geometryChange after calling rescaleChildren, by geometryChangeChild when a child's bounding rectangle has changed, and when a child is added to the area, but may be called at other times for any reason. By default this does nothing.

Parameters:
childchanged - the child JGoObject that was moved or changed size; this may be null, indicating that everything should be reconsidered
See Also:
geometryChange(org.eclipse.swt.graphics.Rectangle), geometryChangeChild(com.nwoods.jgo.JGoObject, org.eclipse.swt.graphics.Rectangle)

getNumObjects

public int getNumObjects()
Description copied from interface: JGoObjectSimpleCollection
Return the number of top-level objects in the collection.

Specified by:
getNumObjects in interface JGoObjectSimpleCollection

isEmpty

public boolean isEmpty()
Description copied from interface: JGoObjectSimpleCollection
Return true if there are no objects in the collection.

Specified by:
isEmpty in interface JGoObjectSimpleCollection

addObjectAtHead

public JGoListPosition addObjectAtHead(JGoObject obj)
Adds a child to the beginning of this area's list of children, appearing underneath other objects in this area.

If this area is already part of a document, the object will become part of the document.

The object should not already have been a part of the document, unless it is already part of this same area.

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

addObjectAtTail

public JGoListPosition addObjectAtTail(JGoObject obj)
Adds a child to the end of this area's list of children, appearing on top of other objects in this area.

If this area is already part of a document, the object will become part of the document.

The object should not already have been a part of the document, unless it is already part of this same area.

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

insertObjectBefore

public JGoListPosition insertObjectBefore(JGoListPosition pos,
                                          JGoObject obj)
Adds a child to this area before the given position.

If this area is already part of a document, the object will become part of the document.

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

The object should not otherwise already have been a part of the document.

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

insertObjectAfter

public JGoListPosition insertObjectAfter(JGoListPosition pos,
                                         JGoObject obj)
Adds a child to this area after the given position.

If this area is already part of a document, the object will become part of the document.

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

The object should not otherwise already have been a part of the document.

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

bringObjectToFront

public void bringObjectToFront(JGoObject obj)
Moves a child object of this area to the "front" of the z-order. That is, it will appear to be on top of the other objects.

The CHANGED event will have a 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 area.

Specified by:
bringObjectToFront in interface JGoObjectCollection
Parameters:
obj - the object to put on top.

sendObjectToBack

public void sendObjectToBack(JGoObject obj)
Moves a child object of this area to the "back" of the z-order. That is, it will appear to be on the bottom of the other objects.

The CHANGED event will have a 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 area.

Specified by:
sendObjectToBack in interface JGoObjectCollection
Parameters:
obj - the object to put on top.

removeObject

public void removeObject(JGoObject obj)
Removes a child object from this area. If the object is not an immediate child of this area, nothing happens.

Specified by:
removeObject in interface JGoObjectCollection
Parameters:
obj - the child 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.

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)
Description copied from interface: JGoObjectSimpleCollection
Return the position for the next object in the collection. This may recurse through the objects contained by a JGoArea.

Specified by:
getNextObjectPos in interface JGoObjectSimpleCollection
Parameters:
pos - the position previous to that which will be returned.
Returns:
an iterator for the next object in the collection; null if there are no more objects.

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.

addCollection

public final java.util.ArrayList addCollection(JGoObjectSimpleCollection coll,
                                               boolean reparentLinks,
                                               JGoLayer linksLayer)
Move some objects into this area, as immediate children of this group, even if they are part of other areas in this same layer.

This just calls addCollection(ArrayList) with an ArrayList composed of the JGoObjects provided in the argument collection. Making a separate list of the JGoObjects is useful in case there are any changes made to the original JGoObjectSimpleCollection, such as a JGoArea.

Parameters:
coll - the collection of JGoObjects to make children of this area
reparentLinks - whether to call JGoSubGraphBase.reparentAllLinksToSubGraphs to make sure each link belongs to the proper subgraph or layer
linksLayer - the JGoLayer of the document that should hold any top-level links
Returns:
a copy of the list of the objects that were actually added to this area

addCollection

public java.util.ArrayList addCollection(java.util.ArrayList coll,
                                         boolean reparentLinks,
                                         JGoLayer linksLayer)
Move some objects into this area, as immediate children of this group, even if they are part of other areas in this same layer.

This method tries to preserve the links connecting any ports of the objects being moved into this group. Of course, none of the objects to be added to this group may be the group itself nor a parent of this group. The objects must also either belong to no layer or to the same layer as this JGoArea. Just as with the addObjectAtTail method, you may find that you will want to set the Selectable property to false for each of the objects being added to this group. The need for this depends on the behavior you want in your application.

Parameters:
coll - an ArrayList of JGoObjects to make children of this area
reparentLinks - whether to call JGoSubGraphBase.reparentAllLinksToSubGraphs to make sure each link belongs to the proper subgraph or layer
linksLayer - the JGoLayer of the document that should hold any top-level links
Returns:
a copy of the list of the objects that were actually added to this area

copyNewValueForRedo

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

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

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

Overrides:
copyNewValueForRedo in class JGoObject
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)
Description copied from class: JGoObject
This method is called by the JGoDocumentChangedEdit.undo and redo methods to actually perform the property value change for a JGoObject.

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

Overrides:
changeValue in class JGoObject
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