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$

Author:

John Reekie

Pt.AcceptedRating:

Yellow

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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

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.

getFigureCount

public int getFigureCount()

Return the number of elements in this container.

Specified by:

getFigureCount in interface FigureContainer

Specified by:

getFigureCount in class AbstractFigureContainer

Returns:

The number of figures.

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

Returns:

the outline shape of this figure

getTransformContext

public TransformContext getTransformContext()

Return the transform context of this figure.

Specified by:

getTransformContext in interface CanvasComponent

Overrides:

getTransformContext in class AbstractFigure

Returns:

The tranformation context.

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.