diva.canvas
Interface ZList

All Superinterfaces:

FigureSet

All Known Implementing Classes:

BasicZList

public interface ZList
extends FigureSet

A ZList is an interface for objects that contain an ordered list of figures in z-order. In addition to the methods inherited from FigureChildren, ZList has methods for reordering figures in the list, and in the future may have methods for locating objects in 2D space. This interface is used to isolate the implementation of figure containers from the z-list, to allow future optimization of the z-list implementation. This interface tries to mimic the AWT Container and Swing JLayerPane interfaces where possible. Unfortunately, these two classes differ on the relation between list ordering and display ordering, so we have chosen to use the AWT Container order (high-numbered elements are displayed below lower-numbered elements), since we thought it would make using the add method less error-prone.

Version:

$Id: ZList.java 38798 2005-07-08 20:00:01Z cxh $

Author:

John Reekie

Accepted Rating:

Yellow

Method Summary

void	add(Figure f) Add a figure to the list.
void	add(int index, Figure f) Insert a figure at the given position.
void	clear() Removes all of the figures from this list.
boolean	contains(Figure f) Test if this list contains the given figure.
Figure	get(int index) Return the figure at the given index.
java.awt.geom.Rectangle2D	getBounds() Get the bounding box of all the figures in this list.
GeometricSet	getContainedFigures(java.awt.geom.Rectangle2D region) Get the figures that are entirely contained by the given region.
int	getFigureCount() Return the number of elements in this list.
GeometricSet	getIntersectedFigures(java.awt.geom.Rectangle2D region) Get the figures with bounding boxes that intersect the given region.
int	indexOf(Figure f) Return the index of the given figure in the Z-list.
void	remove(Figure f) Remove the given figure from this list.
void	remove(int index) Remove the figure at the given index from this list.
void	set(int index, Figure f) Replace the figure at the given index with the passed-in figure.
void	setIndex(int index, Figure f) Set the index of the given figure.

Methods inherited from interface diva.canvas.FigureSet

figures, figuresFromBack, figuresFromFront

Method Detail

add

void add(Figure f)

Add a figure to the list. This interface does not define where the new figure will be in the display order (i.e. at the top, bottom, or somewhere else), although implementations may define this. Clients should assume that an implementation of this method does not check if the figure is already contained -- clients are therefore responsible for being bug-free.

add

void add(int index,
         Figure f)

Insert a figure at the given position. To insert the figure just in front of some other figure, use getIndex() to get the other figure's index, and pass index as the first argument. To insert the figure just behind some other figure, pass index+1 as the first argument. To insert so the figure displays over the top of other figures, insert at zero.

Clients should assume that an implementation of this method does not check if the figure is already contained.

clear

void clear()

Removes all of the figures from this list.

contains

boolean contains(Figure f)

Test if this list contains the given figure. As a general rule, the implementation of this method is not required to be efficient -- O(n) in the length of the list is acceptable. Clients should note that, in general, a much better way of making this same test is to check if the parent of the figure is the same object as this list.

Specified by:

contains in interface FigureSet

get

Figure get(int index)

Return the figure at the given index.

Throws:

java.lang.IndexOutOfBoundsException - The index is out of range.

getBounds

java.awt.geom.Rectangle2D getBounds()

Get the bounding box of all the figures in this list.

getContainedFigures

GeometricSet getContainedFigures(java.awt.geom.Rectangle2D region)

Get the figures that are entirely contained by the given region.

getIntersectedFigures

GeometricSet getIntersectedFigures(java.awt.geom.Rectangle2D region)

Get the figures with bounding boxes that intersect the given region. Note that the returned set may contained figures that do not actually intersect the region -- this method only looks at the bounding boxes.

indexOf

int indexOf(Figure f)

Return the index of the given figure in the Z-list. Figures with a higher index are drawn behind figures with a lower index.

Returns:

The index of the given figure, or -1 if the figure is not in this list.

remove

void remove(Figure f)

Remove the given figure from this list.

remove

void remove(int index)

Remove the figure at the given index from this list.

Throws:

java.lang.IndexOutOfBoundsException - The index is out of range.

set

void set(int index,
         Figure f)

Replace the figure at the given index with the passed-in figure.

setIndex

void setIndex(int index,
              Figure f)

Set the index of the given figure. That is, move it in the display list to the given position. To move the figure to just in front of some other figure, use getIndex() to get the other figure's index, and pass index as the first argument. To move the figure to just behind some other figure, pass index+1 as the first argument. (Other figures will have their indexes changed accordingly.)

Clients should assume that an implementation of this method does not check if the figure is already contained -- clients are therefore responsible for being bug-free.

Throws:

java.lang.IndexOutOfBoundsException - The new index is out of range.

getFigureCount

int getFigureCount()

Return the number of elements in this list.