Figure collections

Package:

diva.canvas.collection

Status:

Preliminary. Unpublished.

Last updated:

See also:

The Diva canvas
Copyright

Contents

Overview

A lot of the more primitive operations in an interactive editor involve finding and working with sets of figures that span the hierarchy in unpredictable ways. This package contains a number of interfaces and classes that assist with this process.

Interfaces

interface FigurePredicate
A predicate that can be applied to figures and used to filter them.

boolean apply ( Figure )
Return true if the figure satisfies this predicate, otherwise false.

interface FigureSet

FigureSet is an interface for representing arbitrary set of figures, possibly spanning the hierarchy in unpredictable ways. The contents of the set is not calculated until it is needed, to avoid duplicating large collections of objects.

Enumeration elements ( )
Return an enumeration over the figure in the set.

void filter ( FigurePredicate )
Filter the set, retaining only those figures that satisfy the predicate.

Classes

class Selection implements FigureSet
A selection is a collection of figures that have been "selected." This does not necessarily translate into actual selection on the canvas, but that's usually how it's used.

void add ( Figure )
Add a figure to the selection.

void addItemListener ( ItemListener )
Add an AWT item listener to this selection. The listener will be notified whenever an item is added to or removed from the selection.

void remove ( Figure )
Remove a figure from the selection.

void removeItemListener ( ItemListener )
Remove an AWT item listener from this selection.

void clear ( )
Clear the selection.

class FigureSubtree implements FigureSet

FigureSubtree is a class that contains a sub-tree of the figure hierarchy. The contents of the set is not calculated until it is needed, to avoid duplicating large collections of objects.

FigureSubtree ( FigureCanvas )
Return a set containing all figures on the given canvas.

FigureSubtree ( Layer )
Return a set containing all figures on the given layer.

FigureSubtree ( CompositeFigure )
Return a set containing the given figure and all of its descendents.

abstract class BoundedSet implements FigureSet

BoundedSet is a class that contains figures that are bounded in some way by a rectangular region of a layer. It is designed to support efficient incremental drag-selection.

BoundedSet ( Point2D )
Construct a new bounded set with origin and bound at the given point. The "bound" is the opposite diagonal from the origin, and can be in the positive or negative direction in either axis.

Enumeration freshElements ( )
Return an enumeration of figures added to the set since the most recent call to resize or translate. If there are no fresh elements, this method returns null.

Rectangle2D getBounds ( )
Return the current bounds as a legal rectangle.

boolean isRecursive ( )
Return true if the set is recursively descending into nested figures.

void resize ( double, double )
Resize the bounds by the given distance. The distance can be positive or negative. The elements method will now return the enumeration of all bounded figures. All previously-obtained enumerations are invalid and must be discarded.

void setRecursive ( boolean )
Tell the set to recursively descend into nested figures. The recursion will not go into layers. By default, recursion is turned off.

Enumeration staleElements ( )
Return an enumeration of figures removed from the set since the most recent call to resize or translate. If there are no stale elements, this method returns null.

void translate ( double, double )
Move the whole region by the given distance. The distance can be positive or negative. The elements method will now return the enumeration of all bounded figures. All previously-obtained enumerations are invalid and must be discarded.

class OverlappingBoundedSet extends BoundedSet
This class specializes BoundedSet to include all figures that overlap the bounding region. If recursion is turned on, descendent figures are included only if they also overlap.

class EnclosedBoundedSet extends BoundedSet
This class specializes BoundedSet to include all figures that are enclosed by the bounding region. If recursion is turned on, descendent figures are included only if they are enclosed, even though their parent figures may not be.