Shape

Creates a new shape.

Add another shape to the same view (or composite shape) containing this shape. This method is a convenience shortcut for getShapeParent().add(newShape), but with the added benefit that it does nothing if the receiving shape is not added to a parent (and thus the parent is null).

Gets an animator object that lets the user animate properties of the receiving shape.

For ease of use, the description of the animation desired can be chained directly to the result of this method. For example, the following code fragment would create an animation that runs for 2 seconds, gradually changing the shape's color to red, its position to the top-right corner of the view, and then starts the animation after a delay of 1 second after the method is called:

     shape.animate(2000)
          .delay(1000)
          .color(Color.red)
          .position(Anchor.TOP_RIGHT.ofView())
          .play();

TODO document

Gets a value indicating whether the specified pixel location is contained in the receiver.

Gets a value indicating whether the specified pixel location is contained in the receiver.

By default, this method checks to see whether the point is located within the bounding rectangle of the shape. Shapes where this would produce incorrect results, such as ovals or lines, override this method accordingly.

This method does take the shape's rotation into account. This means that if you subclass Shape and need to provide logic that is different from the default bounding box behavior, then you may need to undo the rotation of the incoming point before testing it against your shape's bounds. The inverseTransformPoint(float, float) method has been provided to simplify this.

Subclasses must implement this method to define how the shape is to be drawn on the canvas. Users should never call this method directly; it is called as part of the repaint cycle by the ShapeView that contains the shape.

Determine whether any part of this shape extends outside the given rectangle.

A convenience method that gets the alpha (opacity) component of the shape's color.

Gets the angular damping of the shape, which is used to reduce the angular velocity of the shape.

Gets the angular velocity of the shape, in degrees per second. (Note that this is different from JBox2D, which uses radians per second. We use degrees for consistency with the rest of the Android graphics subsystem.)

For advanced usage only. Gets the JBox2D Body object that this shape represents.

For advanced usage only. Gets the JBox2D BodyDef object that is used to create the rigid body represented by this shape. A couple caveats:

• The JBox2D Body is created when the shape is added to its parent (a ShapeView or CompositeShape), so changes to the returned BodyDef will only apply before that.
• Do not modify the userData property of the BodyDef object; it is used by Sofia to track the Shape that the Body represents.

Gets the bounding rectangle of the shape. The top-left corner of the bounding rectangle is the shape's origin, and the bottom-right corner is the shape's extent.

Gets the color of the receiver.

Gets the density of the shape. The mass of the shape is computed by multiplying the density of the shape by its surface area.

Gets the coefficient of friction for the shape.

Gets the gravity scaling factory for this shape.

Gets the height of the shape, in pixels.

Gets the x-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default).

Gets the linear damping of the shape, which is used to reduce the linear velocity of the shape.

Gets the linear velocity of the center of mass of the shape, in units per second.

Gets the mass of this shape (which is the density of the shape multiplied by its surface area).

This method can only be called on shapes that are currently added to a ShapeField. If the shape is not in a field, this method will throw an IllegalStateException.

Gets the parent of the receiver.

Gets the location of the centroid of the shape. Be aware that the x and y fields of the returned point may not be valid if layout of the shapes has not yet occurred.

Get the current position anchor, which is an offset relative to the upper left corner of the shape that is used as the shape's "origin" for the purposes of getting/setting x-y positions. The default anchor is the top-left corner (0, 0) unless it has been explicitly set.

Gets the coefficient of restitution, which controls the "bounciness" of the shape (or in more precise terms, the relationship between the velocity of the shape before and after a collision). See setRestitution(float) for ways to interpret this value.

Gets the current angle of rotation of the shape, in degrees clockwise.

Gets the ShapeField that contains this shape.

Gets a value indicating how this shape acts with regard to motion in the physical world.

Gets the y-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default).

Gets the current linear transformation that will be applied to the shape when it is drawn. Currently, the matrix only contains rotation information.

Gets the width of the shape, in pixels.

Gets the z-index of the receiver. A shape with a higher z-index will be drawn on top of a shape with a lower z-index. Among shapes that have the same z-index, shapes added later will be drawn above shapes added earlier. By default, shapes are created with a z-index of 0.

Determine whether this shape intersects another, based on their bounding boxes.

Gets a value indicating whether or not the shape is active. Inactive shapes are drawn on the screen but do not report contact/collisions with other shapes.

Gets a value indicating whether or not the shape is awake.

Gets a value indicating whether this shape is a "bullet." Bullets are very fast moving objects that require more precise contact/collision handling than ordinary objects, and they require more processing power as a result.

Gets a value indicating whether this shape's rotation is fixed -- that is, even under a physical load, the shape will never rotate. This is can be useful for characters in games.

Returns true if this shape is drawn in front of (later than) the other shape.

Gets a value indicating whether or not the shape is a sensor. Sensors are shapes that can be used to detect collisions, but they do not respond physically to those collisions.

Gets a value indicating whether the receiver is visible (drawn on the screen). Invisible shapes also do not receive touch events.

Sets the position of the receiver based on the specified point and anchor, leaving its size unchanged.

Called when the bounds of the shape have been resolved. Subclasses may want to override this if they need to update their state when this occurs.

Remove this shape from its view (or parent).

Increments the shape's rotation by the specified number of degrees, around the same pivot point that was used previously (or the center of the shape if no other pivot has been previously used).

Sets a value indicating whether or not the shape is active. Inactive shapes are drawn on the screen but do not report contact/collisions with other shapes.

A convenience method that sets the alpha (opacity) component of the shape's color without changing the other color components.

Sets the angular damping of the shape, which is used to reduce the angular velocity of the shape. This can be a value between 0.0f (no damping) and POSITIVE_INFINITY (full damping).

Sets the angular velocity of the shape, in degrees per second. (Note that this is different from JBox2D, which uses radians per second. We use degrees for consistency with the rest of the Android graphics subsystem.)

Sets the bounding rectangle of the shape. The bounding rectangle passed to this method is copied, so changes to it after this method is called will not be reflected by the shape.

Sets a value indicating whether this shape is a "bullet." Bullets are very fast moving objects that require more precise contact/collision handling than ordinary objects, and they require more processing power as a result.

Sets the color of the receiver.

Sets the density of the shape. The mass of the shape is computed by multiplying the density of the shape by its surface area.

Sets a value indicating whether this shape's rotation is fixed -- that is, even under a physical load, the shape will never rotate. This is can be useful for characters in games.

Set the coefficient of friction for the shape.

Sets the gravity scaling factor for the shape. This can be used to create interesting gravitational effects for individual shapes; for example, setting it to 0.0 would cause the shape to float in mid-air.

Sets the x-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default). This moves the shape, so calling this method also causes the extent of the shape to change, keeping with width the same.

Sets the linear damping of the shape, which is used to reduce the linear velocity of the shape. This can be a value between 0.0f (no damping) and POSITIVE_INFINITY (full damping).

Sets the linear velocity of the center of mass of the shape, in units per second.

Sets the linear velocity of the center of mass of the shape, in units per second.

Sets the location of the centroid of the shape.

Sets the location of the centroid of the shape.

Set the position anchor, which is an offset relative to the upper left corner of the shape that is used as the shape's "origin" for the purposes of getting/setting x-y positions. This does not change the shape's current position, but will change the behavior of future calls to setX()/setY()/setPosition() and getX()/getY()/getPosition().

Set the position anchor, which is an offset relative to the upper left corner of the shape that is used as the shape's "origin" for the purposes of getting/setting x-y positions. This does not change the shape's current position, but will change the behavior of future calls to setX()/setY()/setPosition() and getX()/getY()/getPosition().

Sets the coefficient of restitution, which controls the "bounciness" of the shape (or in more precise terms, the relationship between the velocity of the shape before and after a collision).

A coefficient of restitution of 0 indicates that the object should effectively "stop" at the point of impact (that is, it will lose all velocity but may still remain in motion due to gravitational effects), while a coefficient of restitution of 1 indicates that the shape's velocity should have the same velocity after the impact as it did before. Coefficients of restitution greater than 1 are also possible; an example would be an object triggering an explosion upon impact and being blasted away.

The physics engine underlying Sofia Graphics does not support negative coefficients of restitution.

Details

Imagine that you have an object being dropped from a height of H and you want to compute the coefficient of restitution that will cause it to reach a height of h after it bounces. This can be computed using the following formula:

.

Similarly, if you have an object traveling at velocity u and you want it to have velocity v after the impact, you can compute the desired restitution with the formula:

.

When two objects in motion collide, the maximum coefficient of restitution of the two objects is used to compute the new velocities after impact. This coefficient is defined to be

.

Finally, the velocities of the objects after a collision can be computed as follows:

and ,

where v_a and v_b are the velocities of the objects after impact, u_a and u_b are the velocities before impact, and m_a and m_b are the masses of the objects.

Sets the angle of rotation of the shape in degrees clockwise, using the center of the shape's bounding box as the pivot point.

Gets a value indicating whether or not the shape is a sensor. Sensors are shapes that can be used to detect collisions, but they do not respond physically to those collisions.

Sets a value indicating how this shape acts with regard to motion in the physical world.

Sets the y-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default). This moves the shape, so calling this method also causes the extent of the shape to change, keeping with height the same.

Sets a value indicating whether the receiver is visible (drawn on the screen).

Sets the z-index of the receiver.

Stops the current animation for this shape, if there is one.

Returns a human-readable string representation of the shape.

This method should only be called internally from within #createFixtures(Body) in order to create fixtures for the shape and add them to the shape's internal list of fixtures.

Called to indicate that the shape needs to be repainted on the screen. Most users will not need to call this method, because modifying a property of the shape such as its color will repaint it automatically.

This method is intended for internal use only, or by advanced users subclassing one of the abstract shape types. Subclasses must override this method to create the necessary fixtures for the body that this shape represents. Use the getB2Body() method to access the body when creating fixtures.

Destroys the fixtures associated with this shape. Most subclasses will not need to call this method directly; instead, they should call recreateFixtures() when the shape changes in a way that requires its fixtures to be recreated (such as when its size changes).

Gets the Paint object that describes how this shape should be drawn. By default, the Paint's style is set to STROKE and the color to the value returned by getColor(). Subclasses can override this method to add their own attributes; they should call the superclass implementation and then add their own styles to the returned object.

Transforms a point on the screen into the original bounds of a shape, pre-rotation. This method is mainly meant to be used by subclasses that need to provide their own contains(float, float) implementation, so that those methods return the correct values when a rotation is applied to the shape.

Called to recalculate the layout of the shape on the screen. Most users will not need to call this method, because modifying a property of the shape such as its position and size will cause the layout to be recalculated automatically.

Destroys and recreates the shape's fixtures. Subclasses should call this method when a property of the shape changes that require its fixtures to be recreated, such as when its size changes.

TODO document

TODO document

TODO document