Package 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$
    Author:
    John Reekie
    Pt.AcceptedRating:
    Yellow
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void add​(int index, Figure f)
      Insert a figure at the given position.
      void add​(Figure f)
      Add a figure to the list.
      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​(int index)
      Remove the figure at the given index from this list.
      void remove​(Figure f)
      Remove the given figure 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.
    • 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.