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$

Author:

John Reekie

Pt.AcceptedRating:

Yellow

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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.
    
    Parameters:
    
    f - The figure to be inserted.
  - 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.
    
    Parameters:
    
    index - The index at which the figure shall be inserted.
    
    f - The figure to be inserted.
  - 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
    
    Parameters:
    
    f - The figure
    
    Returns:
    
    true if the figure is contained by this list.
  - get
```
Figure get(int index)
```
    Return the figure at the given index.
    
    Parameters:
    
    index - The given index
    
    Returns:
    
    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.
    
    Returns:
    
    the bounding box.
  - getContainedFigures
```
GeometricSet getContainedFigures(java.awt.geom.Rectangle2D region)
```
    Get the figures that are entirely contained by the given region.
    
    Parameters:
    
    region - The region.
    
    Returns:
    
    The figures with bounding boxes that are entirely contained by 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.
    
    Parameters:
    
    region - The region.
    
    Returns:
    
    The figures with bounding boxes that intersect the given region.
  - 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.
    
    Parameters:
    
    f - The figure.
    
    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.
    
    Parameters:
    
    f - The figure.
  - remove
```
void remove(int index)
```
    Remove the figure at the given index from this list.
    
    Parameters:
    
    index - The index of the figure.
    
    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.
    
    Parameters:
    
    index - The index of the figure.
    
    f - The 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.
    
    Parameters:
    
    index - The index of the figure.
    
    f - The figure
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - The new index is out of range.
  - getFigureCount
```
int getFigureCount()
```
    Return the number of elements in this list.
    
    Returns:
    
    The figure count.

Interface ZList

Method Summary

Methods inherited from interface diva.canvas.FigureSet

Method Detail

add

add

clear

contains

get

getBounds

getContainedFigures

getIntersectedFigures

indexOf

remove

remove

set

setIndex

getFigureCount