diva.canvas
Class CompositeFigure

java.lang.Object
  diva.canvas.AbstractFigure
      diva.canvas.AbstractFigureContainer
          diva.canvas.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: CompositeFigure.java 48923 2008-03-25 21:19:29Z cxh $

Author:

John Reekie

Accepted Rating:

Yellow

Field Summary

private Figure	_background The background figure
private java.awt.geom.Rectangle2D	_cachedBounds The cached bounding box
private ZList	_children The children.
private TransformContext	_transformContext The transform context

Constructor Summary

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

CompositeFigure(Figure background)
Construct a composite figure with the given figure as its background.

CompositeFigure(ZList zlist)
Create a new composite figure containing no figures, that uses the given z-list for its storage.

Method Summary

void	add(Figure f) Add a child figure to this composite.
void	add(int index, Figure f) Insert a figure at the given position.
boolean	contains(Figure f) Test if the given figure is a child of this composite.
java.util.Iterator	figures() Return an iteration of the children, in an undefined order.
java.util.Iterator	figuresFromBack() Return an iteration of the children, from back to front.
java.util.Iterator	figuresFromFront() Return an iteration of the children, from front to back.
Figure	get(int index) Return the figure at the given index.
Figure	getBackgroundFigure() Get the background figure.
java.awt.geom.Rectangle2D	getBounds() Get the bounding box of this figure.
ZList	getChildren() Get the internal z-list.
int	getFigureCount() Return the number of elements in this container.
java.awt.geom.Point2D	getOrigin() Return the origin of the background figure in the enclosing transform context.
java.awt.Shape	getShape() Get the shape of this figure.
TransformContext	getTransformContext() Return the transform context of this figure.
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.
boolean	intersects(java.awt.geom.Rectangle2D region) Test if this figure intersects the given rectangle.
protected void	invalidateCachedBounds()
void	paint(java.awt.Graphics2D g) Paint this composite figure onto a 2D graphics object.
void	paint(java.awt.Graphics2D g, java.awt.geom.Rectangle2D region) Paint this composite figure onto a 2D graphics object, within the given region.
Figure	pick(java.awt.geom.Rectangle2D region) Get the picked figure.
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.
void	remove(Figure f) Remove the given child from this composite.
void	remove(int index) Remove the figure at the given position in the list.
void	repaint(DamageRegion d) Accept notification that a repaint has occurred somewhere in the hierarchy below this container.
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.
void	setBackgroundFigure(Figure background) Set the background figure.
void	setIndex(int index, Figure f) Set the index of the given figure.
java.lang.String	toString() Return a string description of this figure
void	transform(java.awt.geom.AffineTransform at) Transform this figure with the supplied transform.
void	translate(double x, double y) Translate this figure the given distance.

Methods inherited from class diva.canvas.AbstractFigureContainer

decorate, undecorate

Methods inherited from class diva.canvas.AbstractFigure

contains, getInteractor, getLayer, getParent, getToolTipText, getUserObject, hit, isVisible, repaint, setInteractor, setParent, setToolTipText, setUserObject, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface diva.canvas.VisibleComponent

isVisible, setVisible

Methods inherited from interface diva.canvas.CanvasComponent

getParent, repaint

Field Detail

_background

private Figure _background

The background figure

_cachedBounds

private java.awt.geom.Rectangle2D _cachedBounds

The cached bounding box

_children

private ZList _children

The children.

_transformContext

private TransformContext _transformContext

The transform context

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.

CompositeFigure

public CompositeFigure(Figure background)

Construct a composite figure with the given figure as its background.

Method Detail

add

public void add(Figure f)

Add a child figure to this composite.

add

public void add(int index,
                Figure f)

Insert a figure at the given position.

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

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

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

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

get

public Figure get(int index)

Return the figure at the given index.

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.

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

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.

getFigureCount

public int getFigureCount()

Return the number of elements in this container.

Specified by:

getFigureCount in interface FigureContainer

Specified by:

getFigureCount in class AbstractFigureContainer

getOrigin

public java.awt.geom.Point2D getOrigin()

Return the origin of the background figure in the enclosing transform context.

Specified by:

getOrigin in interface Figure

Overrides:

getOrigin in class AbstractFigure

Returns:

The origin of the background figure.

See Also:

AbstractFigure.getBounds()

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

getTransformContext

public TransformContext getTransformContext()

Return the transform context of this figure.

Specified by:

getTransformContext in interface CanvasComponent

Overrides:

getTransformContext in class AbstractFigure

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.

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

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

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

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

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

remove

public void remove(Figure f)

Remove the given child from this composite.

remove

public void remove(int index)

Remove the figure at the given position in the list.

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

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.

See Also:

figures(), getBackgroundFigure()

setIndex

public void setIndex(int index,
                     Figure f)

Set the index of the given 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

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

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