sofia.micro
Class Actor

java.lang.Object
  extended by greenfoot.sofiainternal.Actor
      extended by sofia.graphics.Shape
          extended by sofia.graphics.ImageShape
              extended by sofia.micro.Actor
Direct Known Subclasses:
Actor, Flower, Net, ScriptableActor, Water

public class Actor
extends sofia.graphics.ImageShape

An Actor is an object (or character) that exists in a "microworld". Every Actor has a location in the world, and an appearance (that is: an icon, image, or shape).

An Actor is not normally instantiated directly, but instead used as a superclass. Create a subclass to represent more specific objects in the world. Every object that is intended to appear in the world must extend Actor. Subclasses can then define their own appearance and behavior.

One of the most important aspects of this class is the 'act' method. This method is called when the 'Act' or 'Run' buttons are activated in the interface. The method here is empty, and subclasses normally provide their own implementations.

Version:
$Date: 2012/08/06 11:13 $
Author:
Stephen Edwards, Last changed by $Author: edwards $

Constructor Summary
Actor()
          Create a new Actor.
Actor(boolean scaleToCell)
          Create a new Actor.
Actor(java.lang.String nickName)
          Create a new Actor.
Actor(java.lang.String nickName, boolean scaleToCell)
          Create a new Actor.
 
Method Summary
 void act()
          The act method is called by the system to give actors a chance to perform some action.
 void addedToWorld(World world)
          This method is called by the system when this actor has been inserted into the world.
 void addOther(Shape newShape)
          Add another shape to the same view (or parent) containing this shape.
 int getGridX()
          Return the x-coordinate of the actor's current location.
 int getGridY()
          Return the y-coordinate of the object's current location.
 Image getImage()
          Returns the image used to represent this actor, as an Image object.
protected
<MyActor extends Actor>
java.util.Set<MyActor>
getIntersectingObjects(java.lang.Class<MyActor> cls)
          Return all the objects that intersect this object.
protected
<MyActor extends Actor>
java.util.Set<MyActor>
getNeighbors(float distance, boolean diagonal, java.lang.Class<MyActor> cls)
          Return the neighbors to this object within a given distance.
 java.lang.String getNickName()
          Get the "nickname" for this object--an assignable name that is used in the toString() representation of this object.
protected
<MyActor extends Actor>
java.util.Set<MyActor>
getObjectsAtOffset(float dx, float dy, java.lang.Class<MyActor> cls)
          Return all objects that intersect the center of the given location (relative to this object's location).
protected
<MyActor extends Actor>
java.util.Set<MyActor>
getObjectsInRange(float radius, java.lang.Class<MyActor> cls)
          Return all objects within range 'radius' around this object.
protected
<MyActor extends Actor>
MyActor
getOneIntersectingObject(java.lang.Class<MyActor> cls)
          Return an object that intersects this object.
protected
<MyActor extends Actor>
MyActor
getOneObjectAtOffset(float dx, float dy, java.lang.Class<MyActor> cls)
          Return one object that is located at the specified cell (relative to this object's location).
 Shape getShape()
          Returns the image used to represent this actor, as a Shape object.
 World getWorld()
          Return the world that this actor lives in.
 void move(int distance)
          Move this actor the specified distance in the direction it is currently facing.
 void remove()
          Remove this shape from its view (or parent).
 void setBounds(android.graphics.RectF newBounds)
          Sets the bounding rectangle of the shape.
 void setGridLocation(int x, int y)
          Assign a new location for this actor.
 void setGridX(int x)
          Assign a new horizontal (x-axis) location for this actor.
 void setGridY(int y)
          Assign a new vertical (y-axis) location for this actor.
 void setImage(Image image)
          Set a bitmap as the image for this actor.
 void setImage(java.lang.String fileName)
          Set an image for this actor from an image file.
 void setNickName(java.lang.String nickName)
          Set the "nickname" for this object--an assignable name that is used in the toString() representation of this object.
 void setPosition(sofia.graphics.PointAndAnchor pointAndAnchor)
          Sets the position of the receiver based on the specified point and anchor, leaving its size unchanged.
 void setPosition(android.graphics.PointF position)
          Sets the origin (top-left corner) of the receiver.
 void setPositionAnchor(sofia.graphics.Anchor anchor)
          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.
 void setPositionAnchor(android.graphics.PointF anchor)
          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.
 void setRotation(double angleInDegrees)
          Set the rotation of this actor.
 void setX(float x)
          Sets the x-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default).
 void setY(float y)
          Sets the y-coordinate of the anchor point of the shape's bounding box (the top-left corner, by default).
 java.lang.String toString()
          Returns a human-readable string representation of the actor.
 void turn(double amount)
          Turn this actor by the specified amount (in degrees).
 void turnTowards(Actor target)
          Turn this actor to face towards another actor (in the same world).
 void turnTowards(int x, int y)
          Turn this actor to face towards a certain location.
 
Methods inherited from class sofia.graphics.ImageShape
getSourceBounds, setBitmap, setSourceBounds, setSourceBounds
 
Methods inherited from class sofia.graphics.Shape
conditionallyRelayout, conditionallyRepaint, contains, contains, extendsOutside, getAlpha, getBounds, getColor, getHeight, getPosition, getPositionAnchor, getRotation, getRotationPivot, getShapeParent, getWidth, getX, getY, getZIndex, intersects, isInFrontOf, isVisible, move, notifyParentOfPositionChange, onBoundsResolved, rotateBy, setAlpha, setColor, setRotation, setRotation, setVisible, setZIndex
 
Methods inherited from class greenfoot.sofiainternal.Actor
_gf_addToWorld, _gf_getBoundingXs, _gf_getBoundingYs, _gf_getDelegate, _gf_getImage, _gf_getIntersectingObjects, _gf_getNeighbours, _gf_getObjectsAtOffset, _gf_getObjectsInRange, _gf_getOneIntersectingObject, _gf_getOneObjectAtOffset, _gf_getRotation, _gf_getX, _gf_getY, _gf_setImage, _gf_setImage, _gf_setLocation, _gf_setRotation, _gf_turn, addedToWorld, containsPoint, intersects
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Actor

public Actor()
Create a new Actor. By default, this actor's image will be scaled to the size of a single grid cell, preserving aspect ratio.


Actor

public Actor(java.lang.String nickName)
Create a new Actor. By default, this actor's image will be scaled to the size of a single grid cell, preserving aspect ratio.

Parameters:
nickName - The nickname for this actor.

Actor

public Actor(boolean scaleToCell)
Create a new Actor.

Parameters:
scaleToCell - If true, the Actor's image will be scaled to the dimensions of a single World grid cell, while preserving aspect ratio. If false, the image will be sized relative to the underlying bitmap or shape.

Actor

public Actor(java.lang.String nickName,
             boolean scaleToCell)
Create a new Actor.

Parameters:
nickName - The nickname for this actor.
scaleToCell - If true, the Actor's image will be scaled to the dimensions of a single World grid cell, while preserving aspect ratio. If false, the image will be sized relative to the underlying bitmap or shape.
Method Detail

act

public void act()
The act method is called by the system to give actors a chance to perform some action. At each action step in the environment, each object's act method is invoked, in unspecified order.

The default implementation does nothing. This method should be overridden in subclasses to implement an actor's behavior.

Overrides:
act in class greenfoot.sofiainternal.Actor

move

public void move(int distance)
Move this actor the specified distance in the direction it is currently facing.

The direction can be set using the setRotation(double) method.

Overrides:
move in class greenfoot.sofiainternal.Actor
Parameters:
distance - The distance to move (in cell-size units). A negative value will move backwards.
See Also:
setGridLocation(int, int)

turn

public void turn(double amount)
Turn this actor by the specified amount (in degrees).

Parameters:
amount - The number of degrees to turn. Positive values turn clockwise.
See Also:
setRotation(double)

turnTowards

public void turnTowards(int x,
                        int y)
Turn this actor to face towards a certain location.

Overrides:
turnTowards in class greenfoot.sofiainternal.Actor
Parameters:
x - The x-coordinate of the cell to turn towards.
y - The y-coordinate of the cell to turn towards.

turnTowards

public void turnTowards(Actor target)
Turn this actor to face towards another actor (in the same world).

Parameters:
target - The actor to turn towards.

getWorld

public World getWorld()
Return the world that this actor lives in.

Overrides:
getWorld in class greenfoot.sofiainternal.Actor
Returns:
The world.

getImage

public Image getImage()
Returns the image used to represent this actor, as an Image object. This image can be modified to change the actor's appearance.

Overrides:
getImage in class sofia.graphics.ImageShape
Returns:
The object's image.

getShape

public Shape getShape()
Returns the image used to represent this actor, as a Shape object. This shape can be modified to change the actor's appearance.

Returns:
The object's image as a shape.

setImage

public void setImage(java.lang.String fileName)
              throws java.lang.IllegalArgumentException
Set an image for this actor from an image file. The file may be in jpeg, gif or png format.

Parameters:
fileName - The name of the image file.
Throws:
java.lang.IllegalArgumentException - If the image cannot be loaded.

setImage

public void setImage(Image image)
Set a bitmap as the image for this actor.

Parameters:
image - The bitmap to use as this actor's image.

getNeighbors

protected <MyActor extends Actor> java.util.Set<MyActor> getNeighbors(float distance,
                                                                      boolean diagonal,
                                                                      java.lang.Class<MyActor> cls)
Return the neighbors to this object within a given distance. This method considers only logical location, ignoring extent of the image. Thus, it is most useful in scenarios where objects are contained in a single cell.

All cells that can be reached in the number of steps given in 'distance' from this object are considered. Steps may be only in the four main directions, or may include diagonal steps, depending on the 'diagonal' parameter. Thus, a distance/diagonal specification of (1,false) will inspect four cells, (1,true) will inspect eight cells.

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
distance - Distance (in cells) in which to look for other objects.
diagonal - If true, include diagonal steps.
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
A set of all neighbors found.

getObjectsAtOffset

protected <MyActor extends Actor> java.util.Set<MyActor> getObjectsAtOffset(float dx,
                                                                            float dy,
                                                                            java.lang.Class<MyActor> cls)
Return all objects that intersect the center of the given location (relative to this object's location).

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
dx - X-coordinate relative to this object's location.
dy - Y-coordinate relative to this object's location.
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
Set of objects at the given offset. The set will include this object, if the offset is zero.

getOneObjectAtOffset

protected <MyActor extends Actor> MyActor getOneObjectAtOffset(float dx,
                                                               float dy,
                                                               java.lang.Class<MyActor> cls)
Return one object that is located at the specified cell (relative to this object's location). Objects found can be restricted to a specific class (and its subclasses) by supplying the 'cls' parameter. If more than one object of the specified class resides at that location, one of them will be chosen and returned.

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
dx - X-coordinate relative to this object's location.
dy - Y-coordinate relative to this object's location.
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
An object at the given location, or null if none found.

getObjectsInRange

protected <MyActor extends Actor> java.util.Set<MyActor> getObjectsInRange(float radius,
                                                                           java.lang.Class<MyActor> cls)
Return all objects within range 'radius' around this object. An object is within range if the distance between its centwr and this object's center is less than or equal to 'radius'.

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
radius - Radius of the circle (in cells).
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
Set of objects within the specified range.

getIntersectingObjects

protected <MyActor extends Actor> java.util.Set<MyActor> getIntersectingObjects(java.lang.Class<MyActor> cls)
Return all the objects that intersect this object. This takes the graphical extent of objects into consideration.

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
Set of intersecting objects.

getOneIntersectingObject

protected <MyActor extends Actor> MyActor getOneIntersectingObject(java.lang.Class<MyActor> cls)
Return an object that intersects this object. This takes the graphical extent of objects into consideration.

Type Parameters:
MyActor - The type of actor to look for, as specified in the cls parameter.
Parameters:
cls - Class of objects to look for (passing 'null' will find all objects).
Returns:
An arbitrary intersecting object of the specified type, if one exists; null otherwise.

addedToWorld

public void addedToWorld(World world)
This method is called by the system when this actor has been inserted into the world. This method can be overridden to implement custom behavior when the actor is inserted into the world.

The default implementation does nothing.

Parameters:
world - The world the object was added to.

getGridX

public int getGridX()
Return the x-coordinate of the actor's current location. The value returned is the horizontal index of the actor's cell in the world.

Returns:
The x-coordinate of the object's current location.
Throws:
java.lang.IllegalStateException - If the actor has not been added into a world.

setGridX

public void setGridX(int x)
Assign a new horizontal (x-axis) location for this actor. This moves the actor to the specified x-axis location, without changing its y-axis location. The location is specified as the x-coordinate of a cell column in the world.

Parameters:
x - The location to move to on the x-axis.
See Also:
setGridLocation(int, int)

setX

public void setX(float x)
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.

Overrides:
setX in class Shape
Parameters:
x - The x-coordinate of the anchor point of the shape's bounding box.
See Also:
Shape.setPositionAnchor(Anchor)

getGridY

public int getGridY()
Return the y-coordinate of the object's current location. The value returned is the vertical index of the actor's cell in the world.

Returns:
The y-coordinate of the actor's current location
Throws:
java.lang.IllegalStateException - If the actor has not been added into a world.

setGridY

public void setGridY(int y)
Assign a new vertical (y-axis) location for this actor. This moves the actor to the specified y-axis location, without changing its x-axis location. The location is specified as the y-coordinate of a cell row in the world.

Parameters:
y - The location to move to on the y-axis.
See Also:
setGridLocation(int, int)

setY

public void setY(float y)
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.

Overrides:
setY in class Shape
Parameters:
y - The y-coordinate of the anchor point of the shape's bounding box.
See Also:
Shape.setPositionAnchor(Anchor)

setGridLocation

public void setGridLocation(int x,
                            int y)
Assign a new location for this actor. This moves the actor to the specified location. The location is specified as the coordinates of a cell in the world.

If this method is overridden it is important to call this method as super.setLocation(x,y) from the overriding method, to avoid infinite recursion.

Parameters:
x - The location to move to on the x-axis.
y - The location to move to on the y-axis.
See Also:
move(int)

setPosition

public void setPosition(android.graphics.PointF position)
Sets the origin (top-left corner) of the receiver.

Overrides:
setPosition in class Shape
Parameters:
position - A PointF object describing the origin of the shape.

setPosition

public void setPosition(sofia.graphics.PointAndAnchor pointAndAnchor)
Sets the position of the receiver based on the specified point and anchor, leaving its size unchanged.

Overrides:
setPosition in class Shape
Parameters:
pointAndAnchor - A PointAndAnchor object describing the position of the shape.

setRotation

public void setRotation(double angleInDegrees)
Set the rotation of this actor. Rotation is expressed as a degree value, range (0..359). Zero degrees is to the east (right-hand side of the world), and the angle increases clockwise.

Parameters:
angleInDegrees - The new rotation amount, expressed as an absolute angle in degrees.

setBounds

public void setBounds(android.graphics.RectF newBounds)
Sets the bounding rectangle of the shape.

Overrides:
setBounds in class Shape
Parameters:
newBounds - The new bounding rectangle of the shape.

setPositionAnchor

public void setPositionAnchor(sofia.graphics.Anchor anchor)
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().

Overrides:
setPositionAnchor in class Shape
Parameters:
anchor - The new position anchor.

setPositionAnchor

public void setPositionAnchor(android.graphics.PointF anchor)
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().

Overrides:
setPositionAnchor in class Shape
Parameters:
anchor - The new position anchor.

addOther

public void addOther(Shape newShape)
Description copied from class: Shape
Add another shape to the same view (or parent) containing this shape.

Overrides:
addOther in class Shape
Parameters:
newShape - The other shape to add.

remove

public void remove()
Description copied from class: Shape
Remove this shape from its view (or parent).

Overrides:
remove in class Shape

getNickName

public java.lang.String getNickName()
Get the "nickname" for this object--an assignable name that is used in the toString() representation of this object.

Returns:
This actor's nickname, or its class name if no nickname has been assigned.

setNickName

public void setNickName(java.lang.String nickName)
Set the "nickname" for this object--an assignable name that is used in the toString() representation of this object.

Parameters:
nickName - The new nickname for this actor. If null, it will "erase" any previously assigned name.

toString

public java.lang.String toString()
Returns a human-readable string representation of the actor.

Overrides:
toString in class Shape
Returns:
A human-readable string representation of the actor.


Greenfoot homepage