Package jpicedt.graphic.model

Class BranchElement

  • All Implemented Interfaces:
    java.lang.Iterable, java.util.Collection, Element, PicObjectConstants
    Direct Known Subclasses:
    Drawing.RootElement, PicGroup
    public abstract class BranchElement
extends AbstractElement
implements java.util.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 Detail

      • children

        protected java.util.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,

        • this first raises the changeLock semaphor,
        • then calls translate() on every children : this in turn make children forward a DrawingEvent to their parent (= this BranchElement), yet this event is trapped here, hence not propagated upward ; note however that children update their own view whatever the value of the changeLock semaphor ;
        • then lower the changeLock semaphor, and fire a change-update event (which in turn will propagate the event upward along the tree).

      • 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​(java.util.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 java.lang.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 java.util.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 -

      • 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 java.awt.geom.Rectangle2D getBoundingBox​(java.awt.geom.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.

      • toString

        public java.lang.String toString()
        Returns a String representing the group for debugging use only.
        Overrides:
        toString in class AbstractElement

      • add

        public boolean add​(java.lang.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 java.util.Collection

      • addAll

        public boolean addAll​(java.util.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 java.util.Collection

      • clear

        public void clear()
        remove all the children
        Specified by:
        clear in interface java.util.Collection

      • size

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

      • isEmpty

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

      • contains

        public boolean contains​(java.lang.Object o)
        Returns true if this collection contains the specified element.
        Specified by:
        contains in interface java.util.Collection

      • iterator

        public java.util.Iterator iterator()
        Returns an iterator over children.
        Specified by:
        iterator in interface java.util.Collection
        Specified by:
        iterator in interface java.lang.Iterable

      • toArray

        public java.lang.Object[] toArray()
        Returns an array containing all of the elements in this collection.
        Specified by:
        toArray in interface java.util.Collection

      • toArray

        public java.lang.Object[] toArray​(java.lang.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 java.util.Collection

      • remove

        public boolean remove​(java.lang.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 java.util.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​(java.util.Collection c)
        Returns true if this BranchElement contains all of the elements in the specified collection.
        Specified by:
        containsAll in interface java.util.Collection

      • removeAll

        public boolean removeAll​(java.util.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 java.util.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​(java.util.Collection c)
        Retains only the elements in this BranchElement that are contained in the specified collection
        Specified by:
        retainAll in interface java.util.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​(java.lang.Object o)
        Specified by:
        equals in interface java.util.Collection
        Overrides:
        equals in class java.lang.Object
        Returns:
        true if the specified object is equal to this collection

      • createFilteredCollection

        public java.util.ArrayList createFilteredCollection​(java.lang.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​(java.lang.Class clazz)
        Returns whether this BranchElement contains objects that are of the same type of inherit from the given clazz.
        Since:
        jpicedt 1.4pre5