edu.neu.ccs.gui
Class PaintableSequence

java.lang.Object
  |
  +--edu.neu.ccs.gui.AbstractPaintable
        |
        +--edu.neu.ccs.gui.AbstractMutatablePaintable
              |
              +--edu.neu.ccs.gui.PaintableSequence

All Implemented Interfaces:

MutatablePaintable, Paintable, SupportsPropertyChange

public class PaintableSequence

extends AbstractMutatablePaintable

A PaintableSequence encapsulates a sequence of Paintable objects.

If a Paintable implements MutatablePaintable, then it is installed in the sequence as is. Otherwise, it is wrapped using a MutatableWrapper prior to being installed. As a consequence, all items in the internal sequence implement MutatablePaintable.

Whenever there is a change in the overall mutator for the sequence, this change is immediately applied to the individual items in the sequence. As a consequence, the individual sequence items maintain their own knowledge of the net mutation that must be applied in paint operations. In particular, as far as geometry is concerned, an individual sequence item may be viewed either as part of the sequence or as a stand-alone MutatablePaintable . This design decision enables interactive manipulation of sequence items to be handled in a natural fashion.

Since:

2.3

Field Summary

static String	REMOVE_PAINTABLE Bound property name to remove one or more paintables.
static String	SET_PAINTABLE Bound property name to set, add, or append one or more paintables.

Fields inherited from class edu.neu.ccs.gui.AbstractMutatablePaintable

SET_MUTATOR

Fields inherited from class edu.neu.ccs.gui.AbstractPaintable

SET_DEFAULT_BOUNDS2D, SET_DEFAULT_CENTER, SET_OPACITY, SET_VISIBLE

Constructor Summary

PaintableSequence()
The default constructor with an empty sequence and the mutator strategy usage set to Mutator.MUTATE_AS_ITEMS.

PaintableSequence(Paintable[] paintables)
The constructor that sets up the paintable sequence using an initial array of Paintable objects.

PaintableSequence(Paintable[] paintables, Mutator.StrategyUsage usage)
The constructor that sets up the paintable sequence using an initial array of Paintable objects and the given choice of mutator strategy usage.

Method Summary

void	addPaintable(int index, Paintable paintable) Installs a Paintable as a MutatablePaintable at the given index in the paintable sequence.
void	addPaintableAtTop(Paintable paintable) Installs a Paintable as a MutatablePaintable at the topmost position of the paintable sequence (index 0).
void	addPostMutation(Mutator.Strategy strategy) Adds the mutation determined by the given strategy and by the current setting of the mutator strategy usage.
void	addPreMutation(Mutator.Strategy strategy) Adds the mutation determined by the given strategy and by the current setting of the mutator strategy usage.
void	appendPaintable(Paintable paintable) Appends a Paintable as a MutatablePaintable at the end of the paintable sequence.
void	appendSequence(Paintable[] paintables) Appends the given array of Paintable objects to the end of the paintable sequence.
void	clear() Removes all objects from this paintable sequence.
boolean	contains(double x, double y) Tests if a point specified by coordinates is inside this sequence.
Rectangle2D	getBounds2D() Returns the bounds of the paintable based on the default settings or on more detailed computations.
Point2D	getCenter() If the value of getDefaultCenter is non-null, then this value is returned.
int	getIndex(MutatablePaintable mp) Returns the index in the paintable sequence of the given MutatablePaintable.
MutatablePaintable	getMutatablePaintable(int index) Returns the MutatablePaintable at the given index in the sequence.
Mutator.StrategyUsage	getMutatorStrategyUsage() Returns the current mutator strategy usage.
Rectangle2D	getOriginalBounds2D() Returns a copy of the actual bounds of the paintable sequence.
Point2D	getOriginalCenter() Returns a copy of the actual center of the paintable sequence.
MutatablePaintable	hits(double x, double y) If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the appropriate MutatablePaintable object depending on the current Mutator.StrategyUsage setting.
MutatablePaintable	hits(Point2D p) If the point is inside one of the items in the PaintableSequence then this method returns the appropriate MutatablePaintable object depending on the current Mutator.StrategyUsage setting.
MutatablePaintable	hitsItem(double x, double y) If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the topmost MutatablePaintable item that contains the point; otherwise this method returns null.
MutatablePaintable	hitsItem(Point2D p) If the point is inside one of the items in the PaintableSequence then this method returns the topmost MutatablePaintable item that contains the point; otherwise this method returns null.
int	length() Returns the length of the paintable sequence.
void	paint(Graphics g) Paints onto a Graphics context g using information from the paintable sequence and from its individual items.
void	removePaintable(int index) Removes the MutatablePaintable at the given index in the paintable sequence.
void	removePaintable(MutatablePaintable mp) Removes the given MutatablePaintable from the paintable sequence.
void	setMutateAsGroup() Sets the mutator strategy usage to MUTATE_AS_GROUP.
void	setMutateAsItems() Sets the mutator strategy usage to MUTATE_AS_ITEMS.
void	setMutator(AffineTransform M) Sets the mutator transform to the given transform provided that the given transform is invertible.
void	setMutatorStrategyUsage(Mutator.StrategyUsage usage) Set the mutator strategy usage to an allowable setting.
void	setPaintable(int index, Paintable paintable) Installs a Paintable as a MutatablePaintable at the given index in the paintable sequence.
void	setSequence(Paintable[] paintables) Installs the given array of Paintable objects into the paintable sequence and removes the existing objects in the sequence.
void	shiftPaintable(int i, int j) Shift the paintable at index i to index j and shift all paintables in between as needed.
void	shiftPaintable(MutatablePaintable mp, int i) Shift the given mutatable paintable to index i and shift all paintables in between as needed.
void	shiftPaintableDown(int i) Shift the paintable at index i one index closer to the bottom.
void	shiftPaintableDown(MutatablePaintable mp) Shift the given mutatable paintable one index closer to the bottom and shift other paintables as needed.
void	shiftPaintableToBottom(int i) Shift the paintable at index i to the bottom and shift all paintables in between as needed.
void	shiftPaintableToBottom(MutatablePaintable mp) Shift the given mutatable paintable to the bottom and shift other paintables as needed.
void	shiftPaintableToTop(int i) Shift the paintable at index i to the top and shift all paintables in between as needed.
void	shiftPaintableToTop(MutatablePaintable mp) Shift the given mutatable paintable to the top and shift other paintables as needed.
void	shiftPaintableUp(int i) Shift the paintable at index i one index closer to the top.
void	shiftPaintableUp(MutatablePaintable mp) Shift the given mutatable paintable one index closer to the top and shift other paintables as needed.
MutatablePaintable[]	toArray() Returns an array with the MutatablePaintable items in this paintable sequence.
protected MutatablePaintable	wrapPaintable(Paintable paintable) By default, this method returns the result of applying the method PaintableTools.wrapPaintable.

Methods inherited from class edu.neu.ccs.gui.AbstractMutatablePaintable

addPostMutation, addPreMutation, getMutator, getMutatorInverse, move, move

Methods inherited from class edu.neu.ccs.gui.AbstractPaintable

addForwardingListener, addPropertyChangeListener, addPropertyChangeListener, addPropertyChangeListeners, addPropertyChangeListeners, applyOpacity, contains, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getDefaultBounds2D, getDefaultCenter, getForwardingListener, getOpacity, getPreparedGraphics2D, getPropertyChangeListeners, getPropertyChangeListeners, hasListeners, isVisible, possiblyContains, removeAndAddForwardingListener, removeForwardingListener, removePropertyChangeListener, removePropertyChangeListener, setDefaultBounds2D, setDefaultCenter, setOpacity, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface edu.neu.ccs.gui.Paintable

contains, getOpacity, getPreparedGraphics2D, isVisible, setOpacity, setVisible

Field Detail

SET_PAINTABLE

public static String SET_PAINTABLE

Bound property name to set, add, or append one or more paintables.

REMOVE_PAINTABLE

public static String REMOVE_PAINTABLE

Bound property name to remove one or more paintables.

Constructor Detail

PaintableSequence

public PaintableSequence()

The default constructor with an empty sequence and the mutator strategy usage set to Mutator.MUTATE_AS_ITEMS.

See Also:

PaintableSequence(Paintable[]), PaintableSequence(Paintable[], Mutator.StrategyUsage)

PaintableSequence

public PaintableSequence(Paintable[] paintables)

The constructor that sets up the paintable sequence using an initial array of Paintable objects.

If the array is null then the sequence is set to empty.

The array may contain null objects that will, in effect, reserve positions that may later be filled using setPaintable.

Parameters:

paintables - the array of paintables to set

See Also:

PaintableSequence(), PaintableSequence(Paintable[], Mutator.StrategyUsage), appendSequence(Paintable[])

PaintableSequence

public PaintableSequence(Paintable[] paintables,
                         Mutator.StrategyUsage usage)

The constructor that sets up the paintable sequence using an initial array of Paintable objects and the given choice of mutator strategy usage.

If the array is null then the sequence is set to empty.

The array may contain null objects that will, in effect, reserve positions that may later be filled using setPaintable.

Parameters:

paintables - the array of paintables to set

usage - the mutator strategy usage

See Also:

PaintableSequence(), PaintableSequence(Paintable[]), appendSequence(Paintable[]), setMutatorStrategyUsage(Mutator.StrategyUsage)

Method Detail

clear

public final void clear()

Removes all objects from this paintable sequence.

If the existing sequence is non-empty, fires property change: REMOVE_PAINTABLE.

setSequence

public final void setSequence(Paintable[] paintables)

Installs the given array of Paintable objects into the paintable sequence and removes the existing objects in the sequence.

Each Paintable is installed using the protected wrapper method wrapPaintable.

If the existing sequence is non-empty, fires property change: REMOVE_PAINTABLE.

If the given paintables array is non-null and of length greater than zero, fires property change: SET_PAINTABLE.

If the sequence of paintables being set are exactly the same as the sequence of paintables currently installed, then this method will do nothing.

Parameters:

paintables - the array of paintables to set

See Also:

clear(), appendSequence(Paintable []), wrapPaintable(Paintable)

appendSequence

public final void appendSequence(Paintable[] paintables)

Appends the given array of Paintable objects to the end of the paintable sequence.

Each Paintable is installed using the protected wrapper method wrapPaintable.

If the given paintables array is non-null and of length greater than zero, fires property change: SET_PAINTABLE.

Parameters:

paintables - the array of paintables to append

See Also:

setSequence(Paintable []), wrapPaintable(Paintable)

setPaintable

public final void setPaintable(int index,
                               Paintable paintable)

Installs a Paintable as a MutatablePaintable at the given index in the paintable sequence. The object currently at the position in the sequence is replaced.

The Paintable is installed using the protected wrapper method wrapPaintable.

This method does nothing if the index is not in [0, length).

Fires property change: SET_PAINTABLE.

Parameters:

index - the position in the sequence

paintable - the paintable to set at the position

See Also:

addPaintable(int, Paintable), appendPaintable(Paintable), removePaintable(int), getMutatablePaintable(int), wrapPaintable(Paintable)

addPaintable

public final void addPaintable(int index,
                               Paintable paintable)

Installs a Paintable as a MutatablePaintable at the given index in the paintable sequence. All current elements in the sequence from that index onward are displaced by one index position.

The Paintable is installed using the protected wrapper method wrapPaintable.

This method does nothing if the index is not in [0, length]. If the index equals 0, this method is equivalent to addPaintableAtTop. If the index equals length, this method is equivalent to appendPaintable.

Fires property change: SET_PAINTABLE.

Parameters:

index - the position in the sequence

paintable - the paintable to set at the position

See Also:

setPaintable(int, Paintable), appendPaintable(Paintable), removePaintable(int), getMutatablePaintable(int), wrapPaintable(Paintable)

addPaintableAtTop

public final void addPaintableAtTop(Paintable paintable)

Installs a Paintable as a MutatablePaintable at the topmost position of the paintable sequence (index 0). All current elements in the sequence are displaced by one index position.

The Paintable is installed using the protected wrapper method wrapPaintable.

Fires property change: SET_PAINTABLE.

Parameters:

paintable - the paintable to add at the top

See Also:

setPaintable(int, Paintable), appendPaintable(Paintable), removePaintable(int), getMutatablePaintable(int), wrapPaintable(Paintable)

appendPaintable

public final void appendPaintable(Paintable paintable)

Appends a Paintable as a MutatablePaintable at the end of the paintable sequence.

The Paintable is installed using the protected wrapper method wrapPaintable.

Fires property change: SET_PAINTABLE.

Parameters:

paintable - the paintable to append

See Also:

setPaintable(int, Paintable), addPaintable(int, Paintable), removePaintable(int), getMutatablePaintable(int), wrapPaintable(Paintable)

removePaintable

public final void removePaintable(int index)

Removes the MutatablePaintable at the given index in the paintable sequence. All objects in the sequence at higher index positions are displaced to one index position lower.

This method does nothing if the index is not in [0, length).

Fires property change: REMOVE_PAINTABLE.

Parameters:

index - the position in the sequence

See Also:

setPaintable(int, Paintable), addPaintable(int, Paintable), appendPaintable(Paintable), getMutatablePaintable(int)

removePaintable

public final void removePaintable(MutatablePaintable mp)

Removes the given MutatablePaintable from the paintable sequence. All objects in the sequence at higher index positions are displaced to one index position lower.

This method does nothing if the MutatablePaintable is not in the sequence.

Fires property change: REMOVE_PAINTABLE.

See Also:

setPaintable(int, Paintable), addPaintable(int, Paintable), appendPaintable(Paintable), getMutatablePaintable(int)

getMutatablePaintable

public final MutatablePaintable getMutatablePaintable(int index)

Returns the MutatablePaintable at the given index in the sequence.

This method returns null if index is not in [0, length).

Parameters:

index - the position in the sequence

Returns:

the mutatable paintable to get at the position

See Also:

setPaintable(int, Paintable), addPaintable(int, Paintable), appendPaintable(Paintable), removePaintable(int)

getIndex

public final int getIndex(MutatablePaintable mp)

Returns the index in the paintable sequence of the given MutatablePaintable.

The index is also known as the z-index since it represents the order in which items will appear when painted with index 0 in the topmost position.

Returns -1 if the given MutatablePaintable is null or is not in the paintable sequence.

Returns:

the index of the mutatable paintable

length

public final int length()

Returns the length of the paintable sequence.

Returns:

the length of the paintable sequence

shiftPaintable

public final void shiftPaintable(int i,
                                 int j)

Shift the paintable at index i to index j and shift all paintables in between as needed.

Does nothing if the indices i and j are not in the range [0, length) and also does nothing if i == j.

Parameters:

i - the current position of a paintable

j - the new position of the shifted paintable

shiftPaintableToTop

public final void shiftPaintableToTop(int i)

Shift the paintable at index i to the top and shift all paintables in between as needed.

Does nothing if the index i is not in the range [0, length) and also does nothing if i == 0.

Parameters:

i - the current position of a paintable

shiftPaintableToBottom

public final void shiftPaintableToBottom(int i)

Shift the paintable at index i to the bottom and shift all paintables in between as needed.

Does nothing if the index i is not in the range [0, length) and also does nothing if i == (length-1).

Parameters:

i - the current position of a paintable

shiftPaintableUp

public final void shiftPaintableUp(int i)

Shift the paintable at index i one index closer to the top.

Does nothing if the index i is not in the range [0, length) and also does nothing if i == 0.

Parameters:

i - the current position of a paintable

shiftPaintableDown

public final void shiftPaintableDown(int i)

Shift the paintable at index i one index closer to the bottom.

Does nothing if the index i is not in the range [0, length) and also does nothing if i == (length-1).

Parameters:

i - the current position of a paintable

shiftPaintable

public final void shiftPaintable(MutatablePaintable mp,
                                 int i)

Shift the given mutatable paintable to index i and shift all paintables in between as needed.

Does nothing if the given mutatable paintable is not in the sequence.

Does nothing if index i is not in the range [0, length) and also does nothing if the given mutatable paintable is already at index i.

Parameters:

mp - the mutatable paintable to shift

i - the new position of the shifted paintable

shiftPaintableToTop

public final void shiftPaintableToTop(MutatablePaintable mp)

Shift the given mutatable paintable to the top and shift other paintables as needed.

Does nothing if the given mutatable paintable is not in the sequence or is already at the top.

Parameters:

mp - the mutatable paintable to shift

shiftPaintableToBottom

public final void shiftPaintableToBottom(MutatablePaintable mp)

Shift the given mutatable paintable to the bottom and shift other paintables as needed.

Does nothing if the given mutatable paintable is not in the sequence or is already at the bottom.

Parameters:

mp - the mutatable paintable to shift

shiftPaintableUp

public final void shiftPaintableUp(MutatablePaintable mp)

Shift the given mutatable paintable one index closer to the top and shift other paintables as needed.

Does nothing if the given mutatable paintable is not in the sequence or is already at the top.

Parameters:

mp - the mutatable paintable to shift

shiftPaintableDown

public final void shiftPaintableDown(MutatablePaintable mp)

Shift the given mutatable paintable one index closer to the bottom and shift other paintables as needed.

Does nothing if the given mutatable paintable is not in the sequence or is already at the bottom.

Parameters:

mp - the mutatable paintable to shift

toArray

public final MutatablePaintable[] toArray()

Returns an array with the MutatablePaintable items in this paintable sequence.

Returns:

the sequence items in a MutatablePaintable array

paint

public final void paint(Graphics g)

Paints onto a Graphics context g using information from the paintable sequence and from its individual items.

This method applies the bounds and opacity for the overall sequence and then paints each individual item. The order of painting is from index (length - 1) to index 0, that is, the item at index 0 is the topmost entity that is painted.

If the paintable sequence is empty, this method will not paint.

Specified by:

paint in interface Paintable

Specified by:

paint in class AbstractPaintable

Parameters:

g - the graphics context on which to paint

getBounds2D

public final Rectangle2D getBounds2D()

Returns the bounds of the paintable based on the default settings or on more detailed computations.

If the value of getDefaultBounds2D is non-null, then this value is returned. In particular, by setting the default Bounds2D rectangle, this paintable can reserve space even if it is currently empty.

If the value of getDefaultBounds2D is null, then this method returns the value of getOriginalBounds2D. This rule makes sense since mutator transforms are automatically applied to the individual objects in a paintable sequence and therefore there is no difference between mutated bounds and original bounds in this case.

Specified by:

getBounds2D in interface Paintable

Overrides:

getBounds2D in class AbstractMutatablePaintable

Returns:

a copy of the 2-dimensional bounds of the mutated paintable

See Also:

AbstractMutatablePaintable.getBounds2D(), getOriginalBounds2D(), AbstractPaintable.setDefaultBounds2D(Rectangle2D), AbstractPaintable.getDefaultBounds2D()

getCenter

public final Point2D getCenter()

If the value of getDefaultCenter is non-null, then this value is returned.

If the value of getDefaultCenter is null, then this method returns the value of getOriginalCenter.

Specified by:

getCenter in interface Paintable

Overrides:

getCenter in class AbstractMutatablePaintable

Returns:

a copy the center of the mutated paintable

See Also:

AbstractMutatablePaintable.getCenter(), getOriginalCenter(), AbstractPaintable.setDefaultCenter(Point2D), AbstractPaintable.getDefaultCenter()

getOriginalBounds2D

public final Rectangle2D getOriginalBounds2D()

Returns a copy of the actual bounds of the paintable sequence.

The bounds computation ignores any object in the sequence that has zero width or zero height.

If the paintable sequence is effectively empty, this method returns new Rectangle2D.Double().

This method ignores the default Bound2D rectangle to provide a way to determine the actual bounds of the sequence.

Specified by:

getOriginalBounds2D in interface MutatablePaintable

Specified by:

getOriginalBounds2D in class AbstractMutatablePaintable

Returns:

a copy of the actual bounds of the paintable sequence

See Also:

AbstractMutatablePaintable.getBounds2D()

getOriginalCenter

public final Point2D getOriginalCenter()

Returns a copy of the actual center of the paintable sequence.

By default, this method returns the center of the rectangle returned by getOriginalBounds2D().

This method ignores the default center to provide a way to determine the actual center of the sequence.

Specified by:

getOriginalCenter in interface MutatablePaintable

Specified by:

getOriginalCenter in class AbstractMutatablePaintable

Returns:

a copy of the actual center of the paintable sequence

See Also:

getOriginalBounds2D()

setMutator

public final void setMutator(AffineTransform M)

Sets the mutator transform to the given transform provided that the given transform is invertible.

If the given transform is not invertible, the method does nothing.

Whenever there is a change in the overall mutator for the sequence, this change is immediately applied to the individual items in the sequence. As a consequence, the individual sequence items maintain their own knowledge of the net mutation that must be applied in paint operations. In particular, as far as geometry is concerned, an individual sequence item may be viewed either as part of the sequence or as a standalone MutatablePaintable . This design decision enables interactive manipulation of sequence items to be handled in a natural fashion.

Fires property change: SET_MUTATOR.

Specified by:

setMutator in interface MutatablePaintable

Overrides:

setMutator in class AbstractMutatablePaintable

Parameters:

M - the invertible affine transform to set as the mutator

See Also:

addPreMutation(Mutator.Strategy), addPostMutation(Mutator.Strategy)

addPreMutation

public final void addPreMutation(Mutator.Strategy strategy)

Adds the mutation determined by the given strategy and by the current setting of the mutator strategy usage.

If the current mutator strategy usage is MUTATE_AS_GROUP then this method applies the Mutator.Strategy object to the mutator of the paintable sequence as a whole by composition on the right using the original center to construct the pre-mutation.

If the current mutator strategy usage is MUTATE_AS_ITEMS then this method recursively applies the Mutator.Strategy object to the individual items in the paintable sequence.

Fires property change: SET_MUTATOR.

Specified by:

addPreMutation in interface MutatablePaintable

Overrides:

addPreMutation in class AbstractMutatablePaintable

Parameters:

strategy - the mutator strategy to apply

See Also:

setMutator(AffineTransform), addPostMutation(Mutator.Strategy)

addPostMutation

public final void addPostMutation(Mutator.Strategy strategy)

Adds the mutation determined by the given strategy and by the current setting of the mutator strategy usage.

If the current mutator strategy usage is MUTATE_AS_GROUP then this method applies the Mutator.Strategy object to the mutator of the paintable sequence as a whole by composition on the left using the mutated center to construct the post-mutation.

If the current mutator strategy usage is MUTATE_AS_ITEMS then this method recursively applies the Mutator.Strategy object to the individual items in the paintable sequence.

Fires property change: SET_MUTATOR.

Specified by:

addPostMutation in interface MutatablePaintable

Overrides:

addPostMutation in class AbstractMutatablePaintable

Parameters:

strategy - the mutator strategy to apply

See Also:

setMutator(AffineTransform), addPreMutation(Mutator.Strategy)

setMutatorStrategyUsage

public final void setMutatorStrategyUsage(Mutator.StrategyUsage usage)

Set the mutator strategy usage to an allowable setting.

The allowable settings are:

• MUTATE_AS_GROUP: mutate the sequence as a group
• MUTATE_AS_ITEMS: mutate the individual sequence items.

Parameters:

usage - the mutator strategy usage

See Also:

getMutatorStrategyUsage()

getMutatorStrategyUsage

public final Mutator.StrategyUsage getMutatorStrategyUsage()

Returns the current mutator strategy usage.

See Also:

setMutatorStrategyUsage(Mutator.StrategyUsage usage)

setMutateAsGroup

public final void setMutateAsGroup()

Sets the mutator strategy usage to MUTATE_AS_GROUP.

See Also:

setMutatorStrategyUsage(Mutator.StrategyUsage usage)

setMutateAsItems

public final void setMutateAsItems()

Sets the mutator strategy usage to MUTATE_AS_ITEMS.

See Also:

setMutatorStrategyUsage(Mutator.StrategyUsage usage)

contains

public final boolean contains(double x,
                              double y)

Tests if a point specified by coordinates is inside this sequence.

This method returns false if one or more of the following conditions occurs:

• The point is not in the rectangle getBounds2D.
• The method isVisible returns false.

Parameters:

x - the x-coordinate of the point

y - the y-coordinate of the point

Returns:

whether or not a specified point is inside the paintable

hits

public final MutatablePaintable hits(double x,
                                     double y)

If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the appropriate MutatablePaintable object depending on the current Mutator.StrategyUsage setting.

If the strategy usage setting is MUTATE_AS_ITEMS, then this method returns the same MutatablePaintable as the method hitsItem.

If the strategy usage setting is MUTATE_AS_GROUP, then this method returns a reference to this paintable sequence.

If the point is not inside any item of the paintable sequence, then this method returns null.

Parameters:

x - the x-coordinate of the point

y - the y-coordinate of the point

Returns:

the appropriate mutatable paintable or null

hits

public final MutatablePaintable hits(Point2D p)

If the point is inside one of the items in the PaintableSequence then this method returns the appropriate MutatablePaintable object depending on the current Mutator.StrategyUsage setting.

If the strategy usage setting is MUTATE_AS_ITEMS, then this method returns the same MutatablePaintable as the method hitsItem.

If the strategy usage setting is MUTATE_AS_GROUP, then this method returns a reference to this paintable sequence.

If the point is not inside any item of the paintable sequence, then this method returns null.

Parameters:

p - a specified Point2D

Returns:

the appropriate mutatable paintable or null

hitsItem

public final MutatablePaintable hitsItem(double x,
                                         double y)

If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the topmost MutatablePaintable item that contains the point; otherwise this method returns null.

This method returns null if one or more of the following conditions occurs:

• The point is not in the rectangle getBounds2D.
• The method isVisible returns false.

Parameters:

x - the x-coordinate of the point

y - the y-coordinate of the point

Returns:

the topmost item containing the point or null

hitsItem

public final MutatablePaintable hitsItem(Point2D p)

If the point is inside one of the items in the PaintableSequence then this method returns the topmost MutatablePaintable item that contains the point; otherwise this method returns null.

This method returns null if one or more of the following conditions occurs:

• The point is null.
• The point is not in the rectangle getBounds2D.
• The method isVisible returns false.

Parameters:

p - a specified Point2D

Returns:

the topmost item containing the point or null

wrapPaintable

protected MutatablePaintable wrapPaintable(Paintable paintable)

By default, this method returns the result of applying the method PaintableTools.wrapPaintable.

This method may be overridden in a derived class if a more sophisticated wrapping process is desired.

Parameters:

paintable - the paintable to wrap as a mutatable paintable

Returns:

the associated mutatable paintable