com.nwoods.jgo
Class JGoLayer

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

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

A JGoLayer holds a collection of objects in a document. Although these document objects may be spread out all over the document in (X,Y) positions, they are all grouped together in Z order. JGoLayer implements JGoObjectCollection, so JGoLayer provides all the standard methods of determining the number of objects in a layer, adding, re-ordering, and removing objects in a layer, and traversing the collection forwards and backwards.

A JGoDocument is composed of a list of JGoLayers. The next layer after this one is above it in the Z-order, so that all of the objects in that next layer will appear in front of all of the objects in this layer. Similarly, all of the objects in this layer will appear in front of all of the objects in a layer previous to this one.

All of the objects in the layer are top-level objects; i.e. getParent() returns null. Currently you cannot have an area with some parts in one layer and other parts in a different layer.

A layer must be owned by a single document (returned by the getDocument method). Each document is created with one layer initially. Use JGoDocument methods to add, rearrange, or remove layers from a document.

You can control the visibility of all of the objects in a layer by setting the Visible property. Note that calling JGoLayer.setVisible does not call JGoObject.setVisible on each of the objects in the layer.

The modifiable property affects the default view behavior for all of the objects in a layer. If the document is modifiable, you will be able to selectively make some layers read-only.

See Also:
JGoDocument, JGoObject, JGoView, Serialized Form

Constructor Summary
JGoLayer()
          Don't use this constructor--instead call JGoDocument.addLayerAfter or JGoDocument.addLayerBefore.
 
Method Summary
 java.util.ArrayList addCollection(java.util.ArrayList coll, boolean reparentLinks, JGoLayer linkslayer)
          Re-parent some objects to be top-level objects, even if they are part of areas in this same layer.
 java.util.ArrayList addCollection(JGoObjectSimpleCollection coll, boolean reparentLinks, JGoLayer linksLayer)
          Re-parent some objects to be top-level objects, even if they are part of areas in this same layer.
 JGoListPosition addObjectAtHead(JGoObject obj)
          Adds an object behind all other objects in the layer.
 JGoListPosition addObjectAtTail(JGoObject obj)
          Adds an object in front of all other objects in the layer.
 void bringObjectToFront(JGoObject obj)
          Moves an object in front of other objects in the layer (moved to the end of the list of objects).
 JGoListPosition findObject(JGoObject obj)
          Return the position of a specific object in the collection.
 JGoDocument getDocument()
          Return the JGoDocument that this layer is a part of.
 JGoListPosition getFirstObjectPos()
          Return the position of the first object in the collection.
 java.lang.Object getIdentifier()
          Return an object identifying this layer.
 JGoListPosition getLastObjectPos()
          Return the position of the last object in the collection.
 JGoLayer getNextLayer()
          Return the layer in front of this layer, or null if this is the top-most 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 getNumObjects()
          Returns the number of top-level objects in the layer.
 JGoObject getObjectAtPos(JGoListPosition pos)
          Return the object for the given position.
 JGoLayer getPrevLayer()
          Return the layer behind this layer, or null if this is the layer closest to the background.
 JGoListPosition getPrevObjectPos(JGoListPosition pos)
          Return the position of the previous object in the collection.
 JGoListPosition insertObjectAfter(JGoListPosition pos, JGoObject obj)
          Adds an object to the layer after the given position.
 JGoListPosition insertObjectBefore(JGoListPosition pos, JGoObject obj)
          Adds an object to the layer before the given position.
 boolean isEmpty()
          Returns true if the layer contains no objects.
 boolean isModifiable()
          Return whether the user can modify this layer interactively.
 boolean isVisible()
          Return whether the objects in this layer should be visible and take part in other operations such as selection.
 void paint(Graphics2D g, JGoView view, org.eclipse.swt.graphics.Rectangle clipRect)
          Paint all of the objects in this layer.
 JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck, boolean selectableOnly)
          Given a point in document coordinates, return the topmost object of this layer only, that contains that point.
 java.util.ArrayList pickObjects(org.eclipse.swt.graphics.Point p, boolean selectableOnly, java.util.ArrayList coll, int max)
          Return a list of all the JGoObjects in this layer that contain a given point.
 void removeAll()
          Remove all of the objects in this layer, and thus from this document.
 void removeObject(JGoObject obj)
          Removes an object from this layer, and thus from the document.
 JGoObject removeObjectAtPos(JGoListPosition pos)
          Remove an object at specified position from the collection.
 void sendObjectToBack(JGoObject obj)
          Moves an object behind other objects in the layer (moved to the head of the list of objects).
 void setIdentifier(java.lang.Object x)
          Change the layer's identifying object.
 void setModifiable(boolean b)
          Change whether the user is able to modify this layer.
 void setVisible(boolean v)
          Change whether all the objects in this layer are visible.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JGoLayer

public JGoLayer()
Don't use this constructor--instead call JGoDocument.addLayerAfter or JGoDocument.addLayerBefore.

Method Detail

getDocument

public JGoDocument getDocument()
Return the JGoDocument that this layer is a part of.


getNextLayer

public JGoLayer getNextLayer()
Return the layer in front of this layer, or null if this is the top-most layer.


getPrevLayer

public JGoLayer getPrevLayer()
Return the layer behind this layer, or null if this is the layer closest to the background.


getNumObjects

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

Specified by:
getNumObjects in interface JGoObjectSimpleCollection

isEmpty

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

Specified by:
isEmpty in interface JGoObjectSimpleCollection

addObjectAtHead

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

If the object is already a top-level part of this layer, 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 layer.

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 layer. Returns the position of the object in the list. Objects should not be owned directly by both an Area and a Document or Layer, nor by more than one document at a time.

If the object is already a top-level part of this layer, 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 layer.

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 layer 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 Layer, nor by more than one document at a time.

If the object is already a top-level part of this layer, 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 layer.

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 layer 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 Layer, nor by more than one document at a time.

If the object is already a top-level part of this layer, 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 layer.

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 layer (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 layer.

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 layer (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 layer.

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 this layer, and thus from the document.

If the object is not part of this layer, 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.

paint

public void paint(Graphics2D g,
                  JGoView view,
                  org.eclipse.swt.graphics.Rectangle clipRect)
Paint all of the objects in this layer.

Iterate over all of the objects in this layer and paint all of the visible objects whose expanded paint bounding rectangle intersects with the given clipping rectangle.

Parameters:
g - the Graphics2D
view - the JGoView being painted; this is passed on to the JGoObject.paint method
clipRect - a Rectangle in document coordinates

pickObject

public JGoObject pickObject(org.eclipse.swt.graphics.Point pointToCheck,
                            boolean selectableOnly)
Given a point in document coordinates, return the topmost object of this layer only, that contains that point. If selectableOnly is true, only an object that is Selectable will be returned.

If no object is found that contains the given point and that meets the selection criteria, null is returned.

This calls JGoObject.pick to let each object decide if it is pickable. This method returns null if isVisible() is false.

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

pickObjects

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

This examines each of the objects in this layer in reverse order, from front to back. For instances of JGoArea, this will call JGoArea.pickObjects. 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 layer.

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.

addCollection

public final java.util.ArrayList addCollection(JGoObjectSimpleCollection coll,
                                               boolean reparentLinks,
                                               JGoLayer linksLayer)
Re-parent some objects to be top-level objects, even if they are part of areas in this same layer.

This just calls addCollection(ArrayList, boolean) 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 - a collection of JGoObjects
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 a list of objects that have been added to this layer

addCollection

public java.util.ArrayList addCollection(java.util.ArrayList coll,
                                         boolean reparentLinks,
                                         JGoLayer linkslayer)
Re-parent some objects to be top-level objects, even if they are part of 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. This method tries to preserve the links connecting any ports of the nodes being added to this layer. Each object to be added to this layer must either not belong to any layer or must already be part of this layer, although perhaps part of a JGoArea such as a JGoSubGraph. Just as with the addObjectAtTail method, you may find that you will want to set the Selectable property to true for each of the objects being added to this layer. The need for this depends on the behavior you want in your application.

Parameters:
coll - a collection of JGoObjects
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 a list of objects that have been added to this layer

removeAll

public void removeAll()
Remove all of the objects in this layer, and thus from this document.


isVisible

public boolean isVisible()
Return whether the objects in this layer should be visible and take part in other operations such as selection.


setVisible

public void setVisible(boolean v)
Change whether all the objects in this layer are visible.


isModifiable

public boolean isModifiable()
Return whether the user can modify this layer interactively. The value also depends on whether the document is modifiable too-- if the document is not modifiable, no layer will be modifiable. However, if the document is modifiable, each layer's modifiability can be controlled with JGoLayer.setModifiable.

The default value is true.


setModifiable

public void setModifiable(boolean b)
Change whether the user is able to modify this layer. This property does not enable or disable any of the layer 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.

This method only changes the layer's modifiable property. If the document is not modifiable, isModifiable will return false regardless of the layer's modifiable property value.


getIdentifier

public java.lang.Object getIdentifier()
Return an object identifying this layer. Typically this may be a String or an Integer. This property defaults to null.


setIdentifier

public void setIdentifier(java.lang.Object x)
Change the layer's identifying object. Typically this will be a String or an Integer.