public abstract class
ShapeFilter

extends Object
implements Iterable<T>

Inheritance

Class Overview

A chainable filter that lets you search for shapes in a field based on a set of criteria.

Summary

Protected Constructors
ShapeFilter(ShapeFilter<? super ShapeType> previous, String descriptionOfConstraint)
Create a new Filter object.
Public Methods
ShapeSet<ShapeType> all()
Returns the set of all shapes matched by this filter.
ShapeType back()
Gets the shape that is farthest in the background that matches this filter.
int count()
Gets the number of shapes matched by this filter.
String description()
Get a human-readable description of this filter.
boolean equals(Object other)
Determine whether this object is equal to the another.
boolean exist()
Returns true if any shapes were matched by this filter.
ShapeType front()
Gets the shape that is farthest in the foreground that matches this filter.
int hashCode()
ShapeFilter<ShapeType> intersecting(RectF bounds)
Restrict this filter to only match shapes that intersect the specified rectangle.
ShapeFilter<ShapeType> intersecting(float left, float top, float right, float bottom)
Restrict this filter to only match shapes that intersect the specified rectangle.
boolean isEmpty()
Returns true if no shapes were matched by this filter.
Iterator<ShapeType> iterator()
Gets an iterator over all shapes matched by this filter.
ShapeFilter<ShapeType> locatedAt(PointF point)
Restrict this filter to only match shapes that occupy the specified point.
ShapeFilter<ShapeType> locatedAt(float x, float y)
Restrict this filter to only match shapes that occupy the specified point.
ShapeFilter<ShapeType> locatedWithin(PointF point, float radius)
Restrict this filter to only match shapes that are located within the specified radius of a point.
ShapeFilter<ShapeType> locatedWithin(float x, float y, float radius)
Restrict this filter to only match shapes that are located within the specified radius of a point.
ShapeSet<ShapeType> remove()
Removes all of the shapes matched by this filter from the field they are in, and returns the set of those shapes.
String toString()
Get a human-readable description of this filter.
ShapeFilter<ShapeType> withAngularVelocity(Predicate<Number> predicate)
Restrict this filter to only match shapes that are currently in motion with a linear velocity whose magnitude satisfies the specified predicate (less than, greater than, etc.).
ShapeFilter<ShapeType> withAwake(boolean awake)
Restrict this filter to only match shapes with the specified awake state.
<ConstrainedShapeType extends ShapeType extends Shape> ShapeFilter<ConstrainedShapeType> withClass(Class<? extends ConstrainedShapeType> theClass)
Restrict this filter to only match shapes whose classes are the same as, or subclasses of, the specified class.
<ConstrainedShapeType extends ShapeType extends Shape> ShapeFilter<ConstrainedShapeType> withClass(Predicate<Class<? extends ConstrainedShapeType>> predicate)
Restrict this filter to only match shapes whose classes match the specified predicate (such as equalTo(Object) or extending(Class)).
ShapeFilter<ShapeType> withColor(Color color)
Restrict this filter to only match shapes with the specified color.
ShapeFilter<ShapeType> withLinearVelocity(Predicate<Number> predicate)
Restrict this filter to only match shapes that are currently in motion with a linear velocity whose magnitude satisfies the specified predicate (less than, greater than, etc.).
ShapeFilter<ShapeType> withSensor(boolean sensor)
Restrict this filter to only match shapes with the specified sensor property.
Protected Methods
final boolean accept(ShapeType object)
TODO: document.
void addDescriptionOfConstraint(StringBuilder result)
Get a human-readable description of this filter.
World b2World()
Gets the JBox2D world where this filter will be executed.
String describe(ShapeType object)
Get a description of the specified object, suitable for use in a diagnostic message.
String description(boolean plural)
Get a human-readable description of this filter.
final void filter()
TODO: document.
String filteredObjectDescription()
Get a human-readable name for the type of objects to which this filter applies.
String filteredObjectsDescription()
Get the plural form of filteredObjectDescription().
ShapeFilter<? super ShapeType> previousFilter()
TODO: document.
RectF queryBounds()
Gets a bounding box that indicates which subregion of the world should be queried by the filter, or null to query the entire world.
abstract boolean thisFilterAccepts(ShapeType object)
TODO: document.
RectF thisQueryBounds()
Gets a bounding box that indicates which subregion of the world should be queried by the filter, or null to query the entire world.
Methods inherited from class java.lang.Object
Object clone()
boolean equals(Object arg0)
void finalize()
final Class<?> getClass()
int hashCode()
final void notify()
final void notifyAll()
String toString()
final void wait()
final void wait(long arg0, int arg1)
final void wait(long arg0)
Methods inherited from interface java.lang.Iterable
abstract Iterator<T> iterator()

Protected Constructors

protected ShapeFilter (ShapeFilter<? super ShapeType> previous, String descriptionOfConstraint)

Create a new Filter object.

Parameters
previous
The previous filter in the chain of filters.
descriptionOfConstraint
A description of the constraint imposed by this filter (just one step in the chain).

Public Methods

public ShapeSet<ShapeType> all ()

Returns the set of all shapes matched by this filter. The type returned is a ShapeSet, so the shapes will be returned back to front.

Returns

a ShapeSet containing all the shapes matched by this filter

public ShapeType back ()

Gets the shape that is farthest in the background that matches this filter. This is the shape that has the lowest z-index, or if multiple shapes have the same z-index, the one that was added least recently to its field.

Returns

the bottom-most shape in the set, or null if the filter matched no shapes

public int count ()

Gets the number of shapes matched by this filter.

Returns

the number of shapes matched by this filter

public String description ()

Get a human-readable description of this filter.

Returns

A human-readable description of this filter.

public boolean equals (Object other)

Determine whether this object is equal to the another.

Parameters
other
The object to compare against.
Returns

True if this object is equal to the other.

public boolean exist ()

Returns true if any shapes were matched by this filter. This is the opposite of isEmpty().

Returns

true if any shapes were matched by this filter, or false if no shapes were matched

public ShapeType front ()

Gets the shape that is farthest in the foreground that matches this filter. This is the shape that has the highest z-index, or if multiple shapes have the same z-index, the one that was added most recently to its field.

Returns

the frontmost shape in the set, or null if the filter matched no shapes

public int hashCode ()

public ShapeFilter<ShapeType> intersecting (RectF bounds)

Restrict this filter to only match shapes that intersect the specified rectangle.

Parameters
bounds
the intersection rectangle
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> intersecting (float left, float top, float right, float bottom)

Restrict this filter to only match shapes that intersect the specified rectangle.

Parameters
left
the x-coordinate of the left edge of the intersection rectangle
top
the y-coordinate of the top of the intersection rectangle
right
the x-coordinate of the right edge of the intersection rectangle
bottom
the y-coordinate of the bottom of the intersection rectangle
Returns

a new filter with the given restriction

public boolean isEmpty ()

Returns true if no shapes were matched by this filter. This is the opposite of exist().

Returns

true if no shapes were matched by this filter

public Iterator<ShapeType> iterator ()

Gets an iterator over all shapes matched by this filter. The iterator is the same as that which would be returned by the ShapeSet retrieved by calling the all() method, so the shapes are iterated in back-to-front order.

Returns

the iterator over the shapes matched by this filter

public ShapeFilter<ShapeType> locatedAt (PointF point)

Restrict this filter to only match shapes that occupy the specified point.

Parameters
point
the point to test
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> locatedAt (float x, float y)

Restrict this filter to only match shapes that occupy the specified point.

Parameters
x
the x-coordinate of the point
y
the y-coordinate of the point
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> locatedWithin (PointF point, float radius)

Restrict this filter to only match shapes that are located within the specified radius of a point.

Parameters
point
the point at the center of the intersection circle
radius
the radius of the intersection circle
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> locatedWithin (float x, float y, float radius)

Restrict this filter to only match shapes that are located within the specified radius of a point.

Parameters
x
the x-coordinate of the center of the intersection circle
y
the y-coordinate of the center of the intersection circle
radius
the radius of the intersection circle
Returns

a new filter with the given restriction

public ShapeSet<ShapeType> remove ()

Removes all of the shapes matched by this filter from the field they are in, and returns the set of those shapes.

Returns

a ShapeSet containing the shapes that were matched and removed

public String toString ()

Get a human-readable description of this filter.

Returns

A human-readable description of this filter.

public ShapeFilter<ShapeType> withAngularVelocity (Predicate<Number> predicate)

Restrict this filter to only match shapes that are currently in motion with a linear velocity whose magnitude satisfies the specified predicate (less than, greater than, etc.).

Parameters
predicate
the predicate that specifies how the angular velocity of the shape should be compared
Returns

a new filter with the given restriction

See Also
public ShapeFilter<ShapeType> withAwake (boolean awake)

Restrict this filter to only match shapes with the specified awake state.

Parameters
awake
true if the filter should only match shapes that are awake; false if it should only match shapes that are asleep
Returns

a new filter with the given restriction

public ShapeFilter<ConstrainedShapeType> withClass (Class<? extends ConstrainedShapeType> theClass)

Restrict this filter to only match shapes whose classes are the same as, or subclasses of, the specified class. This is equivalent to calling withClass(Predicate.extending(theClass)). If you need to write a filter that only matches the class of the shape exactly and excludes subclasses, then you must call the predicate version of this method directly: withClass(Predicate.equalTo(theClass)).

Parameters
theClass
the class that shapes matching the filter will be instances (or subclasses) of
Returns

a new filter with the given restriction

public ShapeFilter<ConstrainedShapeType> withClass (Predicate<Class<? extends ConstrainedShapeType>> predicate)

Restrict this filter to only match shapes whose classes match the specified predicate (such as equalTo(Object) or extending(Class)).

Parameters
predicate
the predicate that specifies how the class of the shape should be compared
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> withColor (Color color)

Restrict this filter to only match shapes with the specified color.

Parameters
color
the Color of shapes to be matched
Returns

a new filter with the given restriction

public ShapeFilter<ShapeType> withLinearVelocity (Predicate<Number> predicate)

Restrict this filter to only match shapes that are currently in motion with a linear velocity whose magnitude satisfies the specified predicate (less than, greater than, etc.).

Parameters
predicate
the predicate that specifies how the linear velocity of the shape should be compared
Returns

a new filter with the given restriction

See Also
public ShapeFilter<ShapeType> withSensor (boolean sensor)

Restrict this filter to only match shapes with the specified sensor property.

Parameters
sensor
true if the filter should only match sensors; false if it should only match shapes that are not sensors
Returns

a new filter with the given restriction

Protected Methods

protected final boolean accept (ShapeType object)

TODO: document.

Parameters
object
TODO: describe
Returns

TODO: describe

protected void addDescriptionOfConstraint (StringBuilder result)

Get a human-readable description of this filter.

Parameters
result
A StringBuilder to add the description to.
protected World b2World ()

Gets the JBox2D world where this filter will be executed. The default behavior of this method is to ask the previous filter for its world,

protected String describe (ShapeType object)

Get a description of the specified object, suitable for use in a diagnostic message. The default implementation just uses toString() on the object.

Parameters
object
The object to describe.
Returns

a description of the object.

protected String description (boolean plural)

Get a human-readable description of this filter.

Parameters
plural
Whether to generate the singular (false) or plural (true) form of the description.
Returns

A human-readable description of this filter.

protected final void filter ()

TODO: document.

protected String filteredObjectDescription ()

Get a human-readable name for the type of objects to which this filter applies. The result should be in the singular form.

Returns

A human-readable version of the FilteredObjectType.

protected String filteredObjectsDescription ()

Get the plural form of filteredObjectDescription().

Returns

A human-readable version of the plural form of FilteredObjectType.

protected ShapeFilter<? super ShapeType> previousFilter ()

TODO: document.

Returns

TODO: describe

protected RectF queryBounds ()

Gets a bounding box that indicates which subregion of the world should be queried by the filter, or null to query the entire world.

Returns

the bounding box where the query should be executed

protected abstract boolean thisFilterAccepts (ShapeType object)

TODO: document.

Parameters
object
TODO: describe
Returns

TODO: describe

protected RectF thisQueryBounds ()

Gets a bounding box that indicates which subregion of the world should be queried by the filter, or null to query the entire world.

Returns

the bounding box where the query should be executed