http://www.jpicedt.org

jpicedt.graphic.model
Class BranchElement

java.lang.Object
  extended by jpicedt.graphic.model.AbstractElement
      extended by jpicedt.graphic.model.BranchElement
All Implemented Interfaces:
Iterable, Collection, Element, PicObjectConstants
Direct Known Subclasses:
Drawing.RootElement, PicGroup

public abstract class BranchElement
extends AbstractElement
implements Collection

An abstract class for Element's that allow children. The geometry specification mostly delegates to the children of this Element, except for the bounding-box, which is backed by an array of coordinates.

The implementation of the Collection interface is done through calls to addChild, removeChild, children, removeAllChildren, except for the addAll method which is implemented from scratch so as to fire a changed-event only once all elements have been added.
As a result, subclasses only need to override these methods to change the behaviour of content-modifying methods.

This element has only one control point, namely, the bottom-left corner of the bounding box. Moving this point result in a global translation of the element (however no rescale capability is available here using the setPoint() method, use the PicGroup class instead).

Since:
jPicEdt
Author:
Sylvain Reynal

Field Summary
protected  boolean changeLock
          a semaphor that signals a change of state is underway in this BranchElement and it shouldn't process events coming from its children before the change is completed (hence this is used inside forwardChangedUpdate()); set it to true each time you start modifying children in batch mode and you don't want events to be forwarded to the root of the hierarchy before everything is completed (e.g.
protected  ArrayList children
          the array that contains children
protected  double[] ptsX
          an array of X-coordinates representing the two opposite corner of the bounding box that contains all children
protected  double[] ptsY
          an array of Y-coordinates representing the two opposite corner of the bounding box that contains all children
 
Fields inherited from class jpicedt.graphic.model.AbstractElement
attributeSet, parent, view
 
Fields inherited from interface jpicedt.graphic.model.PicObjectConstants
ARROW_GLOBAL_SCALE_LENGTH, ARROW_GLOBAL_SCALE_WIDTH, ARROW_INSET_SCALE, ARROW_LENGTH_SCALE, ARROW_WIDTH_LINEWIDTH_SCALE, ARROW_WIDTH_MINIMUM_MM, BRACKET_LENGTH_SCALE, CROSSHATCH, CROSSHATCH_FILLED, DASH_OPAQUE, DASH_TRANSPARENT, DASH1, DASH2, DASH3, DASHED, DIMEN, DOT_SEP, DOT_SEP1, DOT_SEP2, DOT_SEP3, DOTTED, DOUBLE_COLOR, DOUBLE_LINE, DOUBLE_SEP, FILL_COLOR, FILL_STYLE, HATCH_ANGLE, HATCH_COLOR, HATCH_SEP, HATCH_WIDTH, HLINES, HLINES_FILLED, INNER, LEFT_ARROW, LINE_COLOR, LINE_STYLE, LINE_WIDTH, MIDDLE, NONE, OUTER, OVER_STRIKE, OVER_STRIKE_COLOR, OVER_STRIKE_WIDTH, POLYDOTS_ANGLE, POLYDOTS_CIRCLE, POLYDOTS_DISK, POLYDOTS_PENTAGON, POLYDOTS_PENTAGON_FILLED, POLYDOTS_PLUS, POLYDOTS_SCALE_H, POLYDOTS_SCALE_V, POLYDOTS_SIZE_LINEWIDTH_SCALE, POLYDOTS_SIZE_MINIMUM_MM, POLYDOTS_SQUARE, POLYDOTS_SQUARE_FILLED, POLYDOTS_STYLE, POLYDOTS_SUPERIMPOSE, POLYDOTS_TRIANGLE, POLYDOTS_TRIANGLE_FILLED, PS_POINT, PST_CUSTOM, RBRACKET_LENGTH_SCALE, RIGHT_ARROW, SHADOW, SHADOW_ANGLE, SHADOW_COLOR, SHADOW_SIZE, SOLID, TBAR_WIDTH_LINEWIDTH_SCALE, TBAR_WIDTH_MINIMUM_MM, TEXT_BOX_CIRCLE, TEXT_BOX_NO_FRAME, TEXT_BOX_OVAL, TEXT_BOX_RECTANGLE, TEXT_FRAME, TEXT_HALIGN_CENTER, TEXT_HALIGN_LEFT, TEXT_HALIGN_RIGHT, TEXT_HOR_ALIGN, TEXT_ROTATION, TEXT_VALIGN_BASELINE, TEXT_VALIGN_BOTTOM, TEXT_VALIGN_CENTER, TEXT_VALIGN_TOP, TEXT_VERT_ALIGN, VLINES, VLINES_FILLED
 
Constructor Summary
BranchElement()
          construct a BranchElement with no parent and a default PicAttributeSet
BranchElement(BranchElement src)
          cloning constructor (though with no parent and no view) : 1??) attribute set is deeply copied.
BranchElement(Collection c)
          create a new BranchElement from the content of the given Collection of Element's.
BranchElement(PicAttributeSet attributeSet)
          construct a BranchElement with no parent and the given PicAttributeSet
 
Method Summary
 boolean add(Object o)
          add the given object as a new child of this BranchElement, but only if it's an instance of Element, and return true.
 boolean addAll(Collection c)
          adds all the elements in the given collection that are instance of Element as children of this BranchElement.
 void addChild(Element child)
          add the given child to this BranchElement, setting its parent to this.
 void addChild(int position, Element child)
          insert the given child in this BranchElement at the given position, setting its parent to this, and create a view for the child using the ViewFactory that produced the View for this BranchElement.
 void bringBackward(Element obj)
          Move the given child one position backward, i.e.
 void bringForward(Element obj)
          Move the given child one position forward, i.e.
 void bringToBack(Element obj)
          Move the given child to back (i.e.
 void bringToFront(Element obj)
          Move the given child to front, i.e.
 Iterator children()
           
 void clear()
          remove all the children
abstract  Object clone()
          Returns a clone of this Element
 boolean contains(Element o)
           
 boolean contains(Object o)
          Returns true if this collection contains the specified element.
 boolean containsAll(Collection c)
          Returns true if this BranchElement contains all of the elements in the specified collection.
 boolean containsClass(Class clazz)
          Returns whether this BranchElement contains objects that are of the same type of inherit from the given clazz.
 ArrayList createFilteredCollection(Class clazz)
          Returns a list containing children of this BranchElement that are of the same type or inherit the given clazz.
 boolean equals(Object o)
           
 void forwardChangedUpdate(Element child, DrawingEvent.EventType eventType)
          Called by a child of this BranchElement to inform its parent of some change that occured to it or one of its children.
 boolean getAllowsChildren()
          Returns true if the receiver allows children.
 Rectangle2D getBoundingBox(Rectangle2D r)
          Returns the bounding box (i.e.
 Element getChildAt(int childIndex)
           
 int getChildCount()
           
 int getChildIndex(Element node)
          Returns the index of the given Element in the receivers children.
 int getFirstPointIndex()
          Return the index of the first user-controlled point that can be retrieved by getPoint()
 int getLastPointIndex()
          Return the index of the last user-controlled point that can be retrieved by getPoint()
 PicPoint getPoint(int numPoint, PicPoint src)
          Return the user-controlled point having the given index.
 double getPointX(int numPoint)
          Same as getPoint(), yet return the x-coordinate only.
 double getPointY(int numPoint)
          This default implementation returns ptsY[numPoint].This might be a valid implementation as long as subclasses don't have other control points.
 boolean isEmpty()
           
 boolean isToBack(Element obj)
           
 boolean isToFront(Element obj)
           
 Iterator iterator()
          Returns an iterator over children.
 boolean remove(Object o)
          Removes a single instance of the specified Element from this BranchElement, if it is present AND is instance of Element.
 boolean removeAll(Collection c)
          Removes all this collection's elements that are also contained in the specified collection.
 void removeAllChildren()
          remove all children from this BranchElement, set each child's parent to null.
 void removeChild(Element child)
          remove the given child from this BranchElement, setting its parent to null so that the given child become (possibly) eligible for garbage collection if there are no other reference to it.
 void removeView()
          remove the view that render this element and propagate to children ; this may be used to remove any reference to the view, and render it eligible for garbage collection ; if no View, does nothing.
 void replaceChild(int position, Element newChild)
          replace the child at the given position by the given child
 boolean retainAll(Collection c)
          Retains only the elements in this BranchElement that are contained in the specified collection
 void rotate(PicPoint ptOrg, double angle)
          Rotate this Element by the given angle along the given point
 void scale(double ptOrgX, double ptOrgY, double sx, double sy)
          Scale children by (sx,sy) using (ptOrgX,ptOrgY) as origin ; sx and sy can be negative.
 void scale(PicPoint ptOrg, double sx, double sy)
          Scale children by (sx,sy) using ptOrg as origin ; sx and sy can be negative.
 void setAttribute(PicAttributeName name, Object value)
          set an Attribute for this BranchElement and propagate to children
 void setAttributeSet(PicAttributeSet set)
          set AttributeSet for this BranchElement and propagate to children
 void setPoint(int index, PicPoint pt)
          Deprecated. use setPoint(int, PicPoint, EditPointConstraint) instead.
 void setPoint(int numPoint, PicPoint pt, EditPointConstraint c)
          Set the point indexed by "numPoint" to the given value.
 void setViewFromFactory(ViewFactory f)
          set the view for this Element from the given view factory, then set the view for children.
 void shear(PicPoint ptOrg, double shx, double shy)
          Shear this Element by the given params wrt to the given origin
 int size()
           
 Object[] toArray()
          Returns an array containing all of the elements in this collection.
 Object[] toArray(Object[] a)
          Returns an array containing all of the elements in this collection whose runtime type is that of the specified array.
 String toString()
          Returns a String representing the group for debugging use only.
 void translate(double dx, double dy)
          Translate children by the given vector
protected  void updateBoundingBox()
          Update the bounding box by "unioning" the children's bounding box (actually computes the two specification points defining the diagonal of the box).
 
Methods inherited from class jpicedt.graphic.model.AbstractElement
anchorPointsIterator, fireChangedUpdate, getAttribute, getAttributeSet, getDrawing, getParent, getView, setParent
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Collection
hashCode
 
Methods inherited from interface jpicedt.graphic.model.Element
getName
 

Field Detail

children

protected ArrayList children
the array that contains children


changeLock

protected boolean changeLock
a semaphor that signals a change of state is underway in this BranchElement and it shouldn't process events coming from its children before the change is completed (hence this is used inside forwardChangedUpdate()); set it to true each time you start modifying children in batch mode and you don't want events to be forwarded to the root of the hierarchy before everything is completed (e.g. to get rid of side-effects, or to reduce the burden for the repaint manager).

Example of use : whenever we call translate() on this BranchElement,


ptsX

protected double[] ptsX
an array of X-coordinates representing the two opposite corner of the bounding box that contains all children


ptsY

protected double[] ptsY
an array of Y-coordinates representing the two opposite corner of the bounding box that contains all children

Constructor Detail

BranchElement

public BranchElement()
construct a BranchElement with no parent and a default PicAttributeSet


BranchElement

public BranchElement(PicAttributeSet attributeSet)
construct a BranchElement with no parent and the given PicAttributeSet


BranchElement

public BranchElement(BranchElement src)
cloning constructor (though with no parent and no view) : 1??) attribute set is deeply copied. 2??) source's children are cloned, then the copy is added to this BranchElement


BranchElement

public BranchElement(Collection c)
create a new BranchElement from the content of the given Collection of Element's. Children are cloned as well (i.e. this isa deep copy).

Method Detail

clone

public abstract Object clone()
Description copied from class: AbstractElement
Returns a clone of this Element

Specified by:
clone in interface Element
Specified by:
clone in class AbstractElement
Returns:
a clone of this element

getAllowsChildren

public boolean getAllowsChildren()
Returns true if the receiver allows children. This implementation returns true.

Specified by:
getAllowsChildren in interface Element

getChildAt

public Element getChildAt(int childIndex)
Returns:
the child at the given index, or null if no children

getChildCount

public int getChildCount()
Returns:
the number of children for the element.

children

public Iterator children()
Returns:
an Iterator over children.

getChildIndex

public int getChildIndex(Element node)
Returns the index of the given Element in the receivers children. If the receiver does not contain the given Element, -1 will be returned.


contains

public boolean contains(Element o)
Returns:
whether this BranchElement contains the given child

addChild

public void addChild(Element child)
add the given child to this BranchElement, setting its parent to this. Since a child can't have two parents, this also remove the child from its former parent, if any.
If view is non-null, use the associated ViewFactory to create View's for the new child.


addChild

public void addChild(int position,
                     Element child)
insert the given child in this BranchElement at the given position, setting its parent to this, and create a view for the child using the ViewFactory that produced the View for this BranchElement.


replaceChild

public void replaceChild(int position,
                         Element newChild)
replace the child at the given position by the given child


removeChild

public void removeChild(Element child)
remove the given child from this BranchElement, setting its parent to null so that the given child become (possibly) eligible for garbage collection if there are no other reference to it.


removeAllChildren

public void removeAllChildren()
remove all children from this BranchElement, set each child's parent to null.


getFirstPointIndex

public int getFirstPointIndex()
Description copied from interface: Element
Return the index of the first user-controlled point that can be retrieved by getPoint()

Specified by:
getFirstPointIndex in interface Element
Returns:
the index of the first point that can be retrieved by getPoint This returns PT_ANCHOR.

getLastPointIndex

public int getLastPointIndex()
Description copied from interface: Element
Return the index of the last user-controlled point that can be retrieved by getPoint()

Specified by:
getLastPointIndex in interface Element
Returns:
the index of the last point that can be retrieved by getPoint This returns PT_ANCHOR.

getPointX

public double getPointX(int numPoint)
Description copied from interface: Element
Same as getPoint(), yet return the x-coordinate only.

Specified by:
getPointX in interface Element
Parameters:
numPoint - the point index, should be greater or equal to the value returned by getFirstPointIndex, and lower or equal to getLastPointIndex.
Returns:
the X-coord of the point indexed by numPoint.
Since:
PicEdt 1.0

getPointY

public double getPointY(int numPoint)
This default implementation returns ptsY[numPoint].This might be a valid implementation as long as subclasses don't have other control points.

Specified by:
getPointY in interface Element
Parameters:
numPoint - the point index, should be greater or equal to the value returned by getFirstPointIndex, and lower or equal to getLastPointIndex.
Returns:
the Y-coord of the point indexed by numPoint.
Since:
PicEdt 1.0

getPoint

public PicPoint getPoint(int numPoint,
                         PicPoint src)
Return the user-controlled point having the given index. The general contract in Element is to return an IMMUTABLE instance of PicPoint, so that the only way to alter the geometry of this element is by calling the setPoint method, hence this implementation simply calls getPointX() and getPointY().

Specified by:
getPoint in interface Element
Parameters:
numPoint - the point index, should be greater or equal to the value returned by getFirstPointIndex, and lower or equal to getLastPointIndex.
Returns:
the point indexed by numPoint ; if src is null, allocates a new PicPoint and return it, otherwise directly modifies src and returns it as well for convenience.
Since:
PicEdt 1.0

setPoint

public void setPoint(int index,
                     PicPoint pt)
Deprecated. use setPoint(int, PicPoint, EditPointConstraint) instead.

Set the user-controlled point with the given index to the given value. This default implementation simply call setPoint with a null constraint, then fires a change-update of type GEOMETRY_CHANGE

Specified by:
setPoint in interface Element

setPoint

public void setPoint(int numPoint,
                     PicPoint pt,
                     EditPointConstraint c)
Set the point indexed by "numPoint" to the given value.

Specified by:
setPoint in interface Element
c - a geometry constraint, or null if no particular constraint is being imposed (aka default).

translate

public void translate(double dx,
                      double dy)
Translate children by the given vector

Specified by:
translate in interface Element
Parameters:
dx - The X coordinate of translation vector
dy - The Y coordinate of translation vector
Since:
jPicEdt

scale

public void scale(PicPoint ptOrg,
                  double sx,
                  double sy)
Scale children by (sx,sy) using ptOrg as origin ; sx and sy can be negative.

Specified by:
scale in interface Element
Overrides:
scale in class AbstractElement

scale

public void scale(double ptOrgX,
                  double ptOrgY,
                  double sx,
                  double sy)
Scale children by (sx,sy) using (ptOrgX,ptOrgY) as origin ; sx and sy can be negative.

Specified by:
scale in interface Element

rotate

public void rotate(PicPoint ptOrg,
                   double angle)
Rotate this Element by the given angle along the given point

Specified by:
rotate in interface Element
Parameters:
angle - rotation angle in radians

shear

public void shear(PicPoint ptOrg,
                  double shx,
                  double shy)
Shear this Element by the given params wrt to the given origin

Specified by:
shear in interface Element

forwardChangedUpdate

public void forwardChangedUpdate(Element child,
                                 DrawingEvent.EventType eventType)
Called by a child of this BranchElement to inform its parent of some change that occured to it or one of its children. This gives a chance to the receiver to update its layout, then to propagate the change-event upward.
This implementation update the bounding-box, then fire a changedUpdate event ONLY if changeLock is false. Otherwise, does nothing (this is the exact semantic behind "changeLock").

Specified by:
forwardChangedUpdate in interface Element
Parameters:
eventType - the event type
child -

setViewFromFactory

public void setViewFromFactory(ViewFactory f)
set the view for this Element from the given view factory, then set the view for children.

Specified by:
setViewFromFactory in interface Element
Overrides:
setViewFromFactory in class AbstractElement

removeView

public void removeView()
remove the view that render this element and propagate to children ; this may be used to remove any reference to the view, and render it eligible for garbage collection ; if no View, does nothing.

Specified by:
removeView in interface Element
Overrides:
removeView in class AbstractElement

bringToBack

public void bringToBack(Element obj)
Move the given child to back (i.e. following z-ordering policy), i.e. removes it from its current position and insert it at position 0
Does nothing if the given child can't be found in this Drawing or is already to back.


bringToFront

public void bringToFront(Element obj)
Move the given child to front, i.e. removes it from its current position and appends to the drawing.
Does nothing if the given obj can't be found in this Drawing or if it's already to front.


bringBackward

public void bringBackward(Element obj)
Move the given child one position backward, i.e. removes it from its current position and insert it one position backward.
Does nothing if the given obj can't be found in this Drawing, or if it's already to back.


bringForward

public void bringForward(Element obj)
Move the given child one position forward, i.e. removes it from its current position and insert it one position forward.
Does nothing if the given obj can't be found in this Drawing, or if it's already to front.


isToBack

public boolean isToBack(Element obj)
Returns:
true if the given object has the lowest z-value of all objects in this drawing.

isToFront

public boolean isToFront(Element obj)
Returns:
true if the given object has the highest z-value of all objects in this drawing.

getBoundingBox

public Rectangle2D getBoundingBox(Rectangle2D r)
Returns the bounding box (i.e. the surrounding rectangle) in double precision Used e.g. to determine the arguments of the \\begin{picture} command.

Straigthforwardly computed from the diagonal

Specified by:
getBoundingBox in interface Element
Returns:
null if this BranchElement has no children
Since:
PicEdt 1.0

updateBoundingBox

protected void updateBoundingBox()
Update the bounding box by "unioning" the children's bounding box (actually computes the two specification points defining the diagonal of the box). Should be called each time the content of this element gets modified : this may include addition or deletion of a child, and modification of a child by the child itself.


setAttributeSet

public void setAttributeSet(PicAttributeSet set)
set AttributeSet for this BranchElement and propagate to children

Specified by:
setAttributeSet in interface Element
Overrides:
setAttributeSet in class AbstractElement
Parameters:
set - a new AttributeSet for this Element ; this actually make a deep copy of the given attribute set beforehands.

setAttribute

public void setAttribute(PicAttributeName name,
                         Object value)
set an Attribute for this BranchElement and propagate to children

Specified by:
setAttribute in interface Element
Overrides:
setAttribute in class AbstractElement

toString

public String toString()
Returns a String representing the group for debugging use only.

Overrides:
toString in class AbstractElement

add

public boolean add(Object o)
add the given object as a new child of this BranchElement, but only if it's an instance of Element, and return true. Return false otherwise

Specified by:
add in interface Collection

addAll

public boolean addAll(Collection c)
adds all the elements in the given collection that are instance of Element as children of this BranchElement.

Specified by:
addAll in interface Collection

clear

public void clear()
remove all the children

Specified by:
clear in interface Collection

size

public int size()
Specified by:
size in interface Collection
Returns:
same as getChildCount

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Collection
Returns:
true if this BranchElement contains no children

contains

public boolean contains(Object o)
Returns true if this collection contains the specified element.

Specified by:
contains in interface Collection

iterator

public Iterator iterator()
Returns an iterator over children.

Specified by:
iterator in interface Iterable
Specified by:
iterator in interface Collection

toArray

public Object[] toArray()
Returns an array containing all of the elements in this collection.

Specified by:
toArray in interface Collection

toArray

public Object[] toArray(Object[] a)
Returns an array containing all of the elements in this collection whose runtime type is that of the specified array.

Specified by:
toArray in interface Collection

remove

public boolean remove(Object o)
Removes a single instance of the specified Element from this BranchElement, if it is present AND is instance of Element.

Specified by:
remove in interface Collection
Parameters:
o - element to be removed from this BranchElement, if present.
Returns:
true if this BranchElement changed as a result of the call

containsAll

public boolean containsAll(Collection c)
Returns true if this BranchElement contains all of the elements in the specified collection.

Specified by:
containsAll in interface Collection

removeAll

public boolean removeAll(Collection c)
Removes all this collection's elements that are also contained in the specified collection. After this call returns, this collection will contain no elements in common with the specified collection.

Specified by:
removeAll in interface Collection
Parameters:
c - elements to be removed from this collection.
Returns:
true if this collection changed as a result of the call

retainAll

public boolean retainAll(Collection c)
Retains only the elements in this BranchElement that are contained in the specified collection

Specified by:
retainAll in interface Collection
Parameters:
c - elements to be retained in this collection.
Returns:
true if this collection changed as a result of the call

equals

public boolean equals(Object o)
Specified by:
equals in interface Collection
Overrides:
equals in class Object
Returns:
true if the specified object is equal to this collection

createFilteredCollection

public ArrayList createFilteredCollection(Class clazz)
Returns a list containing children of this BranchElement that are of the same type or inherit the given clazz.

Since:
jpicedt 1.4pre5

containsClass

public boolean containsClass(Class clazz)
Returns whether this BranchElement contains objects that are of the same type of inherit from the given clazz.

Since:
jpicedt 1.4pre5

http://www.jpicedt.org

Submit a bug : syd@jpicedt.org