edu.neu.ccs.gui
Class PaintableSequence

java.lang.Object
  edu.neu.ccs.gui.AbstractPaintable
      edu.neu.ccs.gui.PaintableSequence

All Implemented Interfaces:

JPTConstants, Paintable, SupportsPropertyChange, SwingConstants

public class PaintableSequence

extends AbstractPaintable

A PaintableSequence encapsulates a sequence of Paintable objects.

In 2.3.5, the class was refactored to be consistent with the new Paintable interface and the new AbstractPaintable class.

In 2.4.0, the methods to set, add, or append a Paintable were changed to accept a general Object instead. This object will be transformed by makePaintable into a Paintable if possible and then added to this sequence. Note that it is possible to put a null object into the sequence.

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 mutation that must be applied in paint operations. In particular, as far as geometry is concerned, each individual sequence item may be viewed either as part of the sequence or as a stand-alone Paintable. This design decision enables interactive manipulation of sequence items to be handled in a natural fashion.

The getMutator method inherited from AbstractPaintable will always return the identity transform.

In 2.4.0, this class was also updated to be consistent with refinements to the Paintable interface.

In 2.6.0, the general features of a background paint and a background tile were added to Paintable and supported in AbstractPaintable. This raised the question of the meaning of the following methods (which until now were synonyms):

• clear()
• clearSequence()

The comments for clearSequence stated explicitly that the method was equivalent to: removeSequence(0,length()). Given this, it was decided to leave the method clearSequence() unchanged and to introduce a new method:

• clearEverything()

This method will clear all data associated with the object and therefore will be compatible with any future extensions. It was also decided that the method clear() will now be a synonym for the new method clearEverything().

Since:

2.3

Version:

2.6.0

Field Summary

private Vector	paintablesequence The vector to hold the paintable sequence.
private Mutator.StrategyUsage	usage The mutator strategy usage for the paintable sequence.

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

SET_BACKGROUND_PAINT, SET_BACKGROUND_TILE

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

REMOVE_PAINTABLE, SET_CLIPPING_SHAPE, SET_DEFAULT_BOUNDS2D, SET_DEFAULT_CENTER, SET_DEFAULT_ORIGINAL_BOUNDS2D, SET_DEFAULT_ORIGINAL_CENTER, SET_MUTATOR, SET_OPACITY, SET_PAINTABLE, SET_VISIBLE, SHIFT_PAINTABLE

Fields inherited from interface edu.neu.ccs.util.JPTConstants

ABOVE, ALIGNMENT, BELOW, BOTTOM_LEFT, BOTTOM_RIGHT, DEFAULT, FONT, INPUT_PROPERTIES, MANDATORY, OPTIONAL, ORIENTATION, TOP_LEFT, TOP_RIGHT, VALUE

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Constructor Summary

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

PaintableSequence(Object[] objects)
The constructor that sets up the paintable sequence using an initial array of objects that is suitably converted via makePaintable.

PaintableSequence(Object[] objects, Mutator.StrategyUsage usage)
The constructor that sets up the paintable sequence using an initial array of objects that is suitably converted via makePaintable and the given choice of mutator strategy usage.

Method Summary

Paintable	addPaintable(int index, Object o) Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the given index in the paintable sequence; all current elements in the sequence from that index onward are displaced by one index position.
Paintable	addPaintable(Object o) Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the top-most position in the paintable sequence; all current elements in the sequence are displaced by one index position.
Paintable	addPaintable(Object o, int index) This method is equivalent to addPaintable(int, Object) but interchanges the order of the arguments.
Paintable	addPaintableAtTop(Object o) This method is equivalent to addPaintable(0, o).
void	addPostMutation(AffineTransform M) Adds the post-mutation for the paintable sequence by recursively setting the post-mutation for each item in the sequence to the given transform.
void	addPostMutation(Mutator.Strategy strategy) Adds a post-mutation determined by the given strategy and by the current setting of the mutator strategy usage.
void	addPreMutation(AffineTransform M) Adds the pre-mutation for the paintable sequence by recursively setting the pre-mutation for each item in the sequence to the given transform.
void	addPreMutation(Mutator.Strategy strategy) Adds a pre-mutation determined by the given strategy and by the current setting of the mutator strategy usage.
Paintable[]	addSequence(int index, Object[] objects) Uses makePaintable to add the given array of objects after suitable conversion into the paintable sequence starting at the given index; returns the array of paintable objects added.
Paintable[]	addSequence(Object[] objects) Uses makePaintable to add the given array of objects after suitable conversion to the top of the paintable sequence.
Paintable[]	addSequence(Object[] objects, int index) This method is equivalent to addSequence(int, Object) but interchanges the order of the arguments.
Paintable[]	addSequenceAtTop(Object[] objects) This method is equivalent to addSequence(objects).
Paintable	appendPaintable(Object o) Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the bottom-most position in the paintable sequence.
Paintable[]	appendSequence(Object[] objects) Uses makePaintable to append the given array of objects after suitable conversion onto the paintable sequence.
Paintable[]	clear() Clears all data associated with the paintable sequence and returns an array with the paintables removed.
Paintable[]	clearEverything() Clears all data associated with the paintable sequence and returns an array with the paintables removed.
Paintable[]	clearSequence() Removes all paintables from this paintable sequence and returns an array with the paintables removed.
XRect	getActualBounds2D() Returns the actual bounds of the original paintable or null if the paintable is effectively empty.
int	getIndex(Paintable paintable) Returns the index in the paintable sequence of the given Paintable.
Mutator.StrategyUsage	getMutatorStrategyUsage() Returns the current mutator strategy usage.
Paintable	getPaintable(int index) Returns the Paintable at the given index in the sequence.
Paintable	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 Paintable object depending on the current Mutator.StrategyUsage setting.
Paintable	hits(Point2D p) If the point is inside one of the items in the PaintableSequence then this method returns the appropriate Paintable object depending on the current Mutator.StrategyUsage setting.
Paintable	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 top-most Paintable item that contains the point; otherwise this method returns null.
Paintable	hitsItem(Point2D p) If the point is inside one of the items in the PaintableSequence then this method returns the top-most Paintable item that contains the point; otherwise this method returns null.
int	hitsItemAtIndex(double x, double y) If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the index of the top-most Paintable item that contains the point; otherwise this method returns -1.
int	hitsItemAtIndex(Point2D p) If the point is inside one of the items in the PaintableSequence then this method returns the index of the top-most Paintable item that contains the point; otherwise this method returns -1.
int	length() Returns the length of the paintable sequence.
Paintable	makePaintable(Object o) Returns a Paintable constructed from the given Object.
boolean	originalContains(double x, double y) Tests if a point specified by coordinates is inside this sequence.
void	originalPaint(Graphics g) Paints onto a Graphics context g using information from the paintable sequence and from its individual items.
Paintable	removePaintable(int index) Removes the Paintable at the given index in the paintable sequence; all objects in the sequence at higher index positions are displaced to one index position lower; returns the paintable removed.
void	removePaintable(Paintable paintable) Removes the given Paintable from the paintable sequence.
Paintable[]	removeSequence(int m, int n) Removes the sequence of paintables starting at the given index m inclusive and ending at the given index n exclusive; returns an array with the paintables removed.
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 for the paintable sequence by recursively setting the mutator for each item in the sequence to the given transform.
void	setMutator(Mutator.Strategy strategy) Sets the mutation determined by the given strategy and by the current setting of the mutator strategy usage.
void	setMutatorStrategyUsage(Mutator.StrategyUsage usage) Set the mutator strategy usage to an allowable setting.
Paintable	setPaintable(int index, Object o) Uses makePaintable to convert the given object to a Paintable and then installs this paintable at the given index in the paintable sequence; the paintable currently at that position in the sequence is replaced.
Paintable	setPaintable(Object o, int index) This method is equivalent to setPaintable(int, Object) but interchanges the order of the arguments.
Paintable[]	setSequence(Object[] objects) Uses makePaintable to install the given array of objects after suitable conversion into the paintable sequence and removes the existing paintables 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(Paintable paintable, int i) Shift the given 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(Paintable paintable) Shift the given 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(Paintable paintable) Shift the given 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(Paintable paintable) Shift the given 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(Paintable paintable) Shift the given paintable one index closer to the top and shift other paintables as needed.
Paintable[]	toArray() Returns an array with the Paintable items in this paintable sequence.

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

addForwardingListener, addPropertyChangeListener, addPropertyChangeListener, addPropertyChangeListeners, addPropertyChangeListeners, affinetransform, applyOpacity, clearBackgroundPaint, clearBackgroundTile, clearBothBackgrounds, contains, contains, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackgroundPaint, getBackgroundTile, getBounds2D, getCenter, getCorner, getDefaultBounds2D, getDefaultCenter, getDefaultOriginalBounds2D, getDefaultOriginalCenter, getForwardingListener, getMutator, getMutatorInverse, getOpacity, getOriginalBounds2D, getOriginalCenter, getPreparedGraphics2D, getPropertyChangeListeners, getPropertyChangeListeners, glide, glidereflect, hasListeners, hreflect, isVisible, lineartransform, makeSnapshot, move, move, moveCenterTo, moveCenterTo, moveCornerTo, moveCornerTo, mutate, mutate, originalContains, paint, paintAsTiles, paintAsTiles, paintAsTiles, paintAt, paintAt, paintAt, paintAt, possiblyContains, reflect, removeAndAddForwardingListener, removeForwardingListener, removePropertyChangeListener, removePropertyChangeListener, rotate, scale, scale, setBackgroundPaint, setBackgroundTile, setDefaultBounds2D, setDefaultCenter, setDefaultOriginalBounds2D, setDefaultOriginalCenter, setOpacity, setVisible, shear, vreflect

Methods inherited from class java.lang.Object

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

Field Detail

paintablesequence

private Vector paintablesequence

The vector to hold the paintable sequence.

usage

private Mutator.StrategyUsage usage

The mutator strategy usage for the paintable sequence.

Constructor Detail

PaintableSequence

public PaintableSequence()

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

PaintableSequence

public PaintableSequence(Object[] objects)

The constructor that sets up the paintable sequence using an initial array of objects that is suitably converted via makePaintable.

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:

objects - the array of objects to convert and set

PaintableSequence

public PaintableSequence(Object[] objects,
                         Mutator.StrategyUsage usage)

The constructor that sets up the paintable sequence using an initial array of objects that is suitably converted via makePaintable 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:

objects - the array of objects to convert and set

usage - the mutator strategy usage

Method Detail

originalPaint

public final void originalPaint(Graphics g)

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

The z-order of painting is from index (length - 1) to index 0, that is, the item at index 0 is the top-most entity that is painted.

As with other paintable entities, it is assumed that this method is called through the paint method so that clipping, antialiasing, and setting the opacity are done by that method.

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

Specified by:

originalPaint in interface Paintable

Specified by:

originalPaint in class AbstractPaintable

Parameters:

g - the graphics context on which to paint

getActualBounds2D

public final XRect getActualBounds2D()

Returns the actual bounds of the original paintable or null if the paintable is effectively empty.

Specified by:

getActualBounds2D in interface Paintable

Specified by:

getActualBounds2D in class AbstractPaintable

originalContains

public final boolean originalContains(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.

Specified by:

originalContains in interface Paintable

Specified by:

originalContains in class AbstractPaintable

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 original paintable

setMutator

public final void setMutator(AffineTransform M)

Sets the mutator for the paintable sequence by recursively setting the mutator for each item in the sequence to the given transform.

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

Because sequence items may also be mutated individually, there is no guarantee that there is one mutator that applies to the sequence as a whole. Therefore, this method does not retain knowledge of any mutator set. As a consequence, the method getMutator will always return the identity transform.

Fires property change: SET_MUTATOR.

Specified by:

setMutator in interface Paintable

Overrides:

setMutator in class AbstractPaintable

Parameters:

M - the invertible affine transform to set as the mutator

addPreMutation

public void addPreMutation(AffineTransform M)

Adds the pre-mutation for the paintable sequence by recursively setting the pre-mutation for each item in the sequence to the given transform.

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

Fires property change: SET_MUTATOR.

Specified by:

addPreMutation in interface Paintable

Overrides:

addPreMutation in class AbstractPaintable

Parameters:

M - the invertible affine transform to add

addPostMutation

public void addPostMutation(AffineTransform M)

Adds the post-mutation for the paintable sequence by recursively setting the post-mutation for each item in the sequence to the given transform.

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

Fires property change: SET_MUTATOR.

Specified by:

addPostMutation in interface Paintable

Overrides:

addPostMutation in class AbstractPaintable

Parameters:

M - the invertible affine transform to add

setMutator

public void setMutator(Mutator.Strategy strategy)

Sets 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 paintable sequence as a whole by using the original center to construct the mutation to set.

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:

setMutator in interface Paintable

Overrides:

setMutator in class AbstractPaintable

Parameters:

strategy - the mutator strategy to apply

addPreMutation

public final void addPreMutation(Mutator.Strategy strategy)

Adds a pre-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 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 Paintable

Overrides:

addPreMutation in class AbstractPaintable

Parameters:

strategy - the mutator strategy to apply

addPostMutation

public final void addPostMutation(Mutator.Strategy strategy)

Adds a post-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 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 Paintable

Overrides:

addPostMutation in class AbstractPaintable

Parameters:

strategy - the mutator strategy to apply

makePaintable

public Paintable makePaintable(Object o)

Returns a Paintable constructed from the given Object.

By default, uses ComponentFactory.makePaintable.

May be overridden in a derived class if the designer has a more sophisticated way to construct a Paintable.

Any override should respect the convention that if the object is already a Paintable then it is returned as is.

Parameters:

o - the object to make into a Paintable

length

public final int length()

Returns the length of the paintable sequence.

setPaintable

public final Paintable setPaintable(int index,
                                    Object o)

Uses makePaintable to convert the given object to a Paintable and then installs this paintable at the given index in the paintable sequence; the paintable currently at that position in the sequence is replaced.

Returns the Paintable installed.

This method does nothing if the index is not in [0, length) where length is the value of the method length() and returns null in this case.

It is possible for this method to install a null Paintable if that is what is returned by makePaintable.

Fires property change: SET_PAINTABLE.

Parameters:

index - the position in the sequence

o - the object convert to a paintable to set at the position

setPaintable

public final Paintable setPaintable(Object o,
                                    int index)

This method is equivalent to setPaintable(int, Object) but interchanges the order of the arguments.

Fires property change: SET_PAINTABLE.

Parameters:

o - the object convert to a paintable to set at the position

index - the position in the sequence

getPaintable

public final Paintable getPaintable(int index)

Returns the Paintable 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

getIndex

public final int getIndex(Paintable paintable)

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

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 top-most position.

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

Parameters:

paintable - the paintable to find

addPaintable

public final Paintable addPaintable(int index,
                                    Object o)

Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the given index in the paintable sequence; all current elements in the sequence from that index onward are displaced by one index position.

Returns the Paintable inserted.

If the given index is 0, then the paintable is inserted as the top-most paintable in the sequence. This is equivalent to calling the 1-argument version of addPaintable.

If the given index is length(), then the paintable is inserted as the bottom-most paintable in the sequence. This is equivalent to calling appendPaintable.

If the given index is less than 0, it is set to 0.

If the given index is greater than length(), it is set to length().

It is possible for this method to insert a null paintable if that is what is returned by makePaintable. This is done to permit the caller to reserve a slot for future additions to the sequence.

Fires property change: SET_PAINTABLE.

Parameters:

index - the position in the sequence

o - the object to convert to a paintable to insert at the position

addPaintable

public final Paintable addPaintable(Object o,
                                    int index)

This method is equivalent to addPaintable(int, Object) but interchanges the order of the arguments.

Fires property change: SET_PAINTABLE.

Parameters:

o - the object to convert to a paintable to insert at the position

index - the position in the sequence

addPaintable

public final Paintable addPaintable(Object o)

Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the top-most position in the paintable sequence; all current elements in the sequence are displaced by one index position.

Returns the Paintable inserted.

This method is equivalent to addPaintable(0, o).

Fires property change: SET_PAINTABLE.

Parameters:

o - the object to convert to a paintable to insert at the top

addPaintableAtTop

public final Paintable addPaintableAtTop(Object o)

This method is equivalent to addPaintable(0, o).

Retained for backward compatibility.

Fires property change: SET_PAINTABLE.

Parameters:

o - the object to convert to a paintable to insert at the top

appendPaintable

public final Paintable appendPaintable(Object o)

Uses makePaintable to convert the given object to a Paintable and then inserts this paintable at the bottom-most position in the paintable sequence.

Returns the Paintable inserted.

This method is equivalent to addPaintable(length(), o).

Fires property change: SET_PAINTABLE.

Parameters:

o - the object to convert to a paintable to insert at the bottom

setSequence

public final Paintable[] setSequence(Object[] objects)

Uses makePaintable to install the given array of objects after suitable conversion into the paintable sequence and removes the existing paintables in the sequence.

Returns the array of paintable objects installed.

Fires property change: REMOVE_PAINTABLE.

Fires property change: SET_PAINTABLE.

Parameters:

objects - the array of objects to install

addSequence

public final Paintable[] addSequence(int index,
                                     Object[] objects)

Uses makePaintable to add the given array of objects after suitable conversion into the paintable sequence starting at the given index; returns the array of paintable objects added.

If the given index is less than 0, it is set to 0.

If the given index is greater than length(), it is set to length().

Fires property change: SET_PAINTABLE.

Parameters:

index - the position in the sequence at which to add

objects - the array of objects to add

addSequence

public final Paintable[] addSequence(Object[] objects,
                                     int index)

This method is equivalent to addSequence(int, Object) but interchanges the order of the arguments.

Fires property change: SET_PAINTABLE.

Parameters:

objects - the array of objects to add

index - the position in the sequence at which to add

addSequence

public final Paintable[] addSequence(Object[] objects)

Uses makePaintable to add the given array of objects after suitable conversion to the top of the paintable sequence.

Returns the array of paintable objects added.

This method is equivalent to addSequence(0, objects).

Fires property change: SET_PAINTABLE.

Parameters:

objects - the array of objects to add at the top

addSequenceAtTop

public final Paintable[] addSequenceAtTop(Object[] objects)

This method is equivalent to addSequence(objects).

Retained for backward compatibility.

Fires property change: SET_PAINTABLE.

Parameters:

objects - the array of objects to add at the top

appendSequence

public final Paintable[] appendSequence(Object[] objects)

Uses makePaintable to append the given array of objects after suitable conversion onto the paintable sequence.

Returns the array of paintable objects appended.

This method is equivalent to addSequence(length(), objects).

Fires property change: SET_PAINTABLE.

Parameters:

objects - the array of objects to append

removePaintable

public final Paintable removePaintable(int index)

Removes the Paintable at the given index in the paintable sequence; all objects in the sequence at higher index positions are displaced to one index position lower; returns the paintable removed.

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

This method may also return null if the paintable at the given index is null.

Fires property change: REMOVE_PAINTABLE.

Parameters:

index - the position of the item to remove

removePaintable

public final void removePaintable(Paintable paintable)

Removes the given Paintable 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 Paintable is not in the sequence.

Place holder entries that were added as null cannot be removed by this method.

Fires property change: REMOVE_PAINTABLE.

Parameters:

paintable - the item to remove

removeSequence

public final Paintable[] removeSequence(int m,
                                        int n)

Removes the sequence of paintables starting at the given index m inclusive and ending at the given index n exclusive; returns an array with the paintables removed.

Forces m and n into range if needed.

Returns an array of length 0 if no paintables are removed.

Fires property change: REMOVE_PAINTABLE.

Parameters:

m - the starting index inclusive

n - the ending index exclusive

clear

public final Paintable[] clear()

Clears all data associated with the paintable sequence and returns an array with the paintables removed.

As of 2.6.0, this method is equivalent to clearEverything().

Fires property change: REMOVE_PAINTABLE.

Fires property change: SET_BACKGROUND_PAINT.

Fires property change: SET_BACKGROUND_TILE.

See Also:

clearEverything(), clearSequence()

clearSequence

public final Paintable[] clearSequence()

Removes all paintables from this paintable sequence and returns an array with the paintables removed.

This method is equivalent to removeSequence(0,length()).

Fires property change: REMOVE_PAINTABLE.

Does not change the background paint or background tile.

See Also:

clear(), clearEverything()

clearEverything

public final Paintable[] clearEverything()

Clears all data associated with the paintable sequence and returns an array with the paintables removed.

Fires property change: REMOVE_PAINTABLE.

Fires property change: SET_BACKGROUND_PAINT.

Fires property change: SET_BACKGROUND_TILE.

See Also:

clear(), clearSequence()

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.

Fires property change: SHIFT_PAINTABLE.

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.

Fires property change: SHIFT_PAINTABLE.

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).

Fires property change: SHIFT_PAINTABLE.

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.

Fires property change: SHIFT_PAINTABLE.

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).

Fires property change: SHIFT_PAINTABLE.

Parameters:

i - the current position of a paintable

shiftPaintable

public final void shiftPaintable(Paintable paintable,
                                 int i)

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

Does nothing if the given 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 paintable is already at index i.

Fires property change: SHIFT_PAINTABLE.

Parameters:

paintable - the paintable to shift

i - the new position of the shifted paintable

shiftPaintableToTop

public final void shiftPaintableToTop(Paintable paintable)

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

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

Fires property change: SHIFT_PAINTABLE.

Parameters:

paintable - the paintable to shift

shiftPaintableToBottom

public final void shiftPaintableToBottom(Paintable paintable)

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

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

Fires property change: SHIFT_PAINTABLE.

Parameters:

paintable - the paintable to shift

shiftPaintableUp

public final void shiftPaintableUp(Paintable paintable)

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

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

Fires property change: SHIFT_PAINTABLE.

Parameters:

paintable - the paintable to shift

shiftPaintableDown

public final void shiftPaintableDown(Paintable paintable)

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

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

Fires property change: SHIFT_PAINTABLE.

Parameters:

paintable - the paintable to shift

toArray

public final Paintable[] toArray()

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

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

getMutatorStrategyUsage

public final Mutator.StrategyUsage getMutatorStrategyUsage()

Returns the current mutator strategy usage.

setMutateAsGroup

public final void setMutateAsGroup()

Sets the mutator strategy usage to MUTATE_AS_GROUP.

setMutateAsItems

public final void setMutateAsItems()

Sets the mutator strategy usage to MUTATE_AS_ITEMS.

hits

public final Paintable 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 Paintable object depending on the current Mutator.StrategyUsage setting.

If the strategy usage setting is MUTATE_AS_ITEMS, then this method returns the same Paintable 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

hits

public final Paintable hits(Point2D p)

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

If the strategy usage setting is MUTATE_AS_ITEMS, then this method returns the same Paintable 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

hitsItem

public final Paintable 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 top-most Paintable item that contains the point; otherwise this method returns null.

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

• The paintable sequence has no items.
• 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

hitsItem

public final Paintable hitsItem(Point2D p)

If the point is inside one of the items in the PaintableSequence then this method returns the top-most Paintable 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 paintable sequence has no items.
• The point is not in the rectangle getBounds2D.
• The method isVisible returns false.

Parameters:

p - a specified Point2D

hitsItemAtIndex

public final int hitsItemAtIndex(double x,
                                 double y)

If the point specified by coordinates is inside one of the items in the PaintableSequence then this method returns the index of the top-most Paintable item that contains the point; otherwise this method returns -1.

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

• The paintable sequence has no items.
• 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

hitsItemAtIndex

public final int hitsItemAtIndex(Point2D p)

If the point is inside one of the items in the PaintableSequence then this method returns the index of the top-most Paintable item that contains the point; otherwise this method returns -1.

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

• The point is null.
• The paintable sequence has no items.
• The point is not in the rectangle getBounds2D.
• The method isVisible returns false.

Parameters:

p - a specified Point2D