Package diva.canvas

Class CompositeFigure

  • All Implemented Interfaces:
    CanvasComponent, Figure, FigureContainer, FigureSet, VisibleComponent, UserObjectContainer
    public class CompositeFigure
extends AbstractFigureContainer
    A CompositeFigure is a figure that contains a set of child figures. It uses a ZList as the internal representation of its children, and implements wrappers for many of the z-list methods to provide flexible access to the contained figures. Note that this class exposes the ability to add and remove children by any client, and is thus intended for use in situations in which the number of child figures is either large or unpredictable. For applications in which the number of children is smaller and predictable, and more restricted access to the children is require, applications should implement a custom subclass of AbstractFigureContainer. For an example, see diva.canvas.toolbox.IconFigure.
    Version:
    $Id$
    Author:
    John Reekie
    Pt.AcceptedRating:
    Yellow

    • Constructor Detail

      • CompositeFigure

        public CompositeFigure()
        Create a new composite figure containing no figures.

      • CompositeFigure

        public CompositeFigure​(ZList zlist)
        Create a new composite figure containing no figures, that uses the given z-list for its storage. If you have a composite figure that you know is going to contain a lot of children, you can give it an optimized z-list.
        Parameters:
        zlist - the z-list used for storage

      • CompositeFigure

        public CompositeFigure​(Figure background)
        Construct a composite figure with the given figure as its background.
        Parameters:
        background - The background

    • Method Detail

      • add

        public void add​(Figure f)
        Add a child figure to this composite.
        Parameters:
        f - The figure to be added.

      • add

        public void add​(int index,
                Figure f)
        Insert a figure at the given position.
        Parameters:
        index - The index of the figure
        f - The figure to be inserted.

      • contains

        public boolean contains​(Figure f)
        Test if the given figure is a child of this composite. Note that this method, although provided, should not actually be used for performance reasons -- instead, test if the parent of the child is the same as this composite.
        Specified by:
        contains in interface FigureContainer
        Specified by:
        contains in interface FigureSet
        Specified by:
        contains in class AbstractFigureContainer
        Parameters:
        f - The figure to be searched for
        Returns:
        true if the figure is contained.

      • figures

        public java.util.Iterator figures()
        Return an iteration of the children, in an undefined order. This does not include the background figure, even if there is one.
        Specified by:
        figures in interface FigureSet
        Specified by:
        figures in class AbstractFigureContainer
        Returns:
        The iterator.

      • figuresFromBack

        public java.util.Iterator figuresFromBack()
        Return an iteration of the children, from back to front. This is the order in which the children are painted. This does not include the background figure, even if there is one.
        Specified by:
        figuresFromBack in interface FigureSet
        Specified by:
        figuresFromBack in class AbstractFigureContainer
        Returns:
        The iterator

      • figuresFromFront

        public java.util.Iterator figuresFromFront()
        Return an iteration of the children, from front to back. This is the order in which events are intercepted. This does not include the background figure, even if there is one.
        Specified by:
        figuresFromFront in interface FigureSet
        Specified by:
        figuresFromFront in class AbstractFigureContainer
        Returns:
        The iterator

      • get

        public Figure get​(int index)
        Return the figure at the given index.
        Parameters:
        index - the index of the figure.
        Returns:
        The figure.
        Throws:
        java.lang.IndexOutOfBoundsException - The index is out of range.

      • getBackgroundFigure

        public Figure getBackgroundFigure()
        Get the background figure. The background figure is treated specially; its shape is the one returned by getShape(), and most of the methods that return iterators over figures (such as figures()) do not include the background figure.
        Returns:
        The background figure
        See Also:
        figures(), setBackgroundFigure(Figure)

      • getBounds

        public java.awt.geom.Rectangle2D getBounds()
        Get the bounding box of this figure. If the figure hasn't changed since last time, as indicated by repaint() not having been called here or by any descendents, a cached copy of the bounding box will be returned, otherwise a new one will be generated.
        Specified by:
        getBounds in interface Figure
        Overrides:
        getBounds in class AbstractFigure
        Returns:
        the bounding box of this figure.

      • getChildren

        public ZList getChildren()
        Get the internal z-list. Clients must not modify the z-list, but can use it for making queries on its contents.
        Returns:
        The internal z-list.

      • getShape

        public java.awt.Shape getShape()
        Get the shape of this figure. This will be the shape of the background if there is one, otherwise the bounding box.
        Specified by:
        getShape in interface Figure
        Specified by:
        getShape in class AbstractFigure
        Returns:
        the outline shape of this figure

      • indexOf

        public int indexOf​(Figure f)
        Return the index of the given figure in the Z-list, or -1 if the figure is not in this list.
        Parameters:
        f - The figure
        Returns:
        The index of the figure

      • intersects

        public boolean intersects​(java.awt.geom.Rectangle2D region)
        Test if this figure intersects the given rectangle.
        Specified by:
        intersects in interface Figure
        Overrides:
        intersects in class AbstractFigure
        Parameters:
        region - The rectangle to be checked.
        Returns:
        truen if the figure intersects the given rectangle.

      • invalidateCachedBounds

        protected void invalidateCachedBounds()

      • paint

        public void paint​(java.awt.Graphics2D g)
        Paint this composite figure onto a 2D graphics object. This implementation pushes the transform context onto the transform stack, and then paints all children.
        Specified by:
        paint in interface VisibleComponent
        Overrides:
        paint in class AbstractFigureContainer
        Parameters:
        g - The 2D graphics object that this object it to be painted upon.

      • paint

        public void paint​(java.awt.Graphics2D g,
                  java.awt.geom.Rectangle2D region)
        Paint this composite figure onto a 2D graphics object, within the given region. If the figure is not visible, return immediately. Otherwise paint all figures that overlap the given region, from back to front.
        Specified by:
        paint in interface VisibleComponent
        Overrides:
        paint in class AbstractFigure
        Parameters:
        g - The 2D graphics object that this object it to be painted upon.
        region - The region.

      • pick

        public Figure pick​(java.awt.geom.Rectangle2D region)
        Get the picked figure. This method recursively traverses the tree until it finds a figure that is "hit" by the region. Note that a region is given instead of a point so that a "pick halo" can be implemented. If no child is hit, testif the background figure is hit. If still no figure is hit, return null. Note that the region should not have zero size, or no figure will be hit.
        Specified by:
        pick in interface FigureContainer
        Overrides:
        pick in class AbstractFigureContainer
        Parameters:
        region - The rectangle
        Returns:
        The figure

      • pick

        public Figure pick​(java.awt.geom.Rectangle2D region,
                   Filter filter)
        Given a rectangle, return the top-most descendent figure that it hits that is accepted by the given filter. If none does, return null.
        Specified by:
        pick in interface FigureContainer
        Overrides:
        pick in class AbstractFigureContainer
        Parameters:
        region - The rectangle
        filter - The filter
        Returns:
        the Figure or null.

      • remove

        public void remove​(Figure f)
        Remove the given child from this composite.
        Parameters:
        f - The figure to be removed

      • remove

        public void remove​(int index)
        Remove the figure at the given position in the list.
        Parameters:
        index - The index of the figure to be removed.
        Throws:
        java.lang.IndexOutOfBoundsException - The index is out of range.

      • repaint

        public void repaint​(DamageRegion d)
        Accept notification that a repaint has occurred somewhere in the hierarchy below this container. This method overrides the inherited method to clear the cached bounding box, and then forwards the notification to the parent.
        Specified by:
        repaint in interface CanvasComponent
        Overrides:
        repaint in class AbstractFigureContainer
        Parameters:
        d - The region where a repaint has occurred.

      • setBackgroundFigure

        public void setBackgroundFigure​(Figure background)
        Set the background figure. The background figure is treated specially; its shape is the one returned by getShape(), and most of the methods that return iterators over figures (such as figures()) do not include the background figure.
        Parameters:
        background - The background of the figure.
        See Also:
        figures(), getBackgroundFigure()

      • setIndex

        public void setIndex​(int index,
                     Figure f)
        Set the index of the given figure.
        Parameters:
        index - The index
        f - The figure
        Throws:
        java.lang.IndexOutOfBoundsException - The new index is out of range.

      • replaceChild

        protected void replaceChild​(Figure child,
                            Figure replacement)
        Replace the first figure, which must be a child, with the second, which must not be a child.
        Specified by:
        replaceChild in class AbstractFigureContainer
        Parameters:
        child - The figure to be replaced.
        replacement - The replacement figure.

      • toString

        public java.lang.String toString()
        Return a string description of this figure
        Overrides:
        toString in class java.lang.Object

      • transform

        public void transform​(java.awt.geom.AffineTransform at)
        Transform this figure with the supplied transform. This method modifies the transform context with the transform.
        Specified by:
        transform in interface Figure
        Overrides:
        transform in class AbstractFigureContainer
        Parameters:
        at - The transform to be used.

      • translate

        public void translate​(double x,
                      double y)
        Translate this figure the given distance. This method modifies the transform context with the transform.
        Specified by:
        translate in interface Figure
        Overrides:
        translate in class AbstractFigureContainer
        Parameters:
        x - The x value to be moved.
        y - The y value to be moved.