greenfoot
Class Actor

java.lang.Object
  extended by greenfoot.Actor

public abstract class Actor
extends java.lang.Object

An Actor is an object that exists in the greenfoot world. Every Actor has a location in the world, and an appearance (that is: an icon). An Actor is not normally instantiated, but instead used as a superclass to 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 behaviour. One of the most important aspects of this class is the 'act' method. This method is called when the 'Act' or 'Play' buttons are activated in the greenfoot interface. The method here is empty, and subclasses normally provide their own implementations.

Version:
1.0
Author:
Poul Henriksen

Field Summary
(package private)  greenfoot.World world
          Reference to the world that this actor is a part of.
(package private)  int x
          x-coordinate of the object's location in the world.
(package private)  int y
          y-coordinate of the object's location in the world.
 
Constructor Summary
Actor()
          Construct an Actor.
 
Method Summary
 void act()
          The act method is called by the greenfoot framework to give objects a chance to perform some action.
protected  void addedToWorld(greenfoot.World world)
          This method will be called by the Greenfoot system when the object has been inserted into the world.
(package private)  boolean contains(int dx, int dy)
          Checks whether the specified relative cell-location is considered to be inside this object.
(package private)  greenfoot.util.Circle getBoundingCircle()
          Get the bounding circle of the object.
(package private)  java.lang.Object getData()
           
(package private)  greenfoot.GreenfootImage getDisplayImage()
          Get the image to use when displaying this actor.
 int getHeight()
          Return the height of the object.
 greenfoot.GreenfootImage getImage()
          Returns the image used to represent this Actor.
protected  java.util.List getIntersectingObjects(java.lang.Class cls)
          Return all the objects that intersect this object.
protected  java.util.List getNeighbours(int distance, boolean diagonal, java.lang.Class cls)
          Return the neighbours to this object within a given distance.
protected  java.util.List getObjectsAtOffset(int dx, int dy, java.lang.Class cls)
          Return all objects that intersect the given location (relative to this object's location).
protected  java.util.List getObjectsInRange(int r, java.lang.Class cls)
          Return all objects within range 'r' around this object.
protected  Actor getOneIntersectingObject(java.lang.Class cls)
          Return an object that intersects this object.
protected  Actor getOneObjectAtOffset(int dx, int dy, java.lang.Class cls)
          Return one object that is located at the specified cell (relative to this objects location).
(package private) static rmiextension.wrappers.RObject getRObject(java.lang.Object obj)
          Gets the remote reference to the obj.
 int getRotation()
          Return the current rotation of the object.
 int getWidth()
          Return the width of the object.
 greenfoot.World getWorld()
          Return the world that this object lives in.
 int getX()
          Return the x-coordinate of the object's current location.
 int getY()
          Return the y-coordinate of the object's current location.
protected  boolean intersects(Actor other)
          Check whether this object intersects with another given object.
(package private)  boolean isUsingClassImage()
          Check whether the object is using the class image.
(package private)  void setData(java.lang.Object o)
           
 void setImage(greenfoot.GreenfootImage image)
          Set the image for this object to the specified image.
 void setImage(java.lang.String filename)
          Set an image for this object from an image file.
 void setLocation(int x, int y)
          Assign a new location for this object.
(package private)  void setLocationInPixels(int x, int y)
          Translates the given location into cell-coordinates before setting the location.
 void setRotation(int rotation)
          Set the rotation of the object.
(package private)  void setWorld(greenfoot.World world)
          Sets the world of this actor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

world

greenfoot.World world
Reference to the world that this actor is a part of.


x

int x
x-coordinate of the object's location in the world. The object is centered around this location.


y

int y
y-coordinate of the object's location in the world. The object is centered aroudn this location.

Constructor Detail

Actor

public Actor()
Construct an Actor. The object will have a default image.

Method Detail

act

public void act()
The act method is called by the greenfoot framework to give objects a chance to perform some action. At each action step in the environment, each object's act method is invoked, in unspecified order. This method does nothing. It should be overridden in subclasses to implement an object's action.


addedToWorld

protected void addedToWorld(greenfoot.World world)
This method will be called by the Greenfoot system when the object has been inserted into the world. This method can be overridden to implement custom behavoiur when the actor is inserted into the world.

This default implementation is empty.

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

contains

boolean contains(int dx,
                 int dy)
Checks whether the specified relative cell-location is considered to be inside this object.

A location is considered to be inside an object, if the object's image overlaps at least partially with that cell.

This method is used by collision checking methods. Therefor, this method can be overridden if, for example, other than rectangular image shapes should be considered.

NOTE: Does not take rotation into consideration.
NOTE: No longer public, since no scenarios have used it so far, and we might want to do it sligthly different if we want collision checkers to only do most of the computation once pr. act.

Parameters:
dx - The x-position relative to the location of the object
dy - The y-position relative to the location of the object
Returns:
True if the image contains the cell. If the object has no image, false will be returned.

getBoundingCircle

greenfoot.util.Circle getBoundingCircle()
Get the bounding circle of the object. Taking into consideration that the object can rotate.


getData

java.lang.Object getData()

getDisplayImage

greenfoot.GreenfootImage getDisplayImage()
Get the image to use when displaying this actor. This should be whatever was set using setImage(). The returned image should not be modified as it may be the original class image.

Returns:
The image to use to display the actor

getHeight

public int getHeight()
Return the height of the object. The height is the number of cells that an object's image overlaps vertically.

Returns:
The height of the object, or -1 if it has no image.
Throws:
java.lang.IllegalStateException - If there is no world instantiated.

getImage

public greenfoot.GreenfootImage getImage()
Returns the image used to represent this Actor. This image can be modified to change the object's appearance.

If you override this method, you should call super.getImage() before doing anything else.

Returns:
The object's image.

getIntersectingObjects

protected java.util.List getIntersectingObjects(java.lang.Class cls)
Return all the objects that intersect this object. This takes the graphical extent of objects into consideration.
NOTE: Does not take rotation into consideration.

Parameters:
cls - Class of objects to look for (passing 'null' will find all objects).

getNeighbours

protected java.util.List getNeighbours(int distance,
                                       boolean diagonal,
                                       java.lang.Class cls)
Return the neighbours 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.

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 list of all neighbours found.

getObjectsAtOffset

protected java.util.List getObjectsAtOffset(int dx,
                                            int dy,
                                            java.lang.Class cls)
Return all objects that intersect the given location (relative to this object's location).

Parameters:
dx - X-coordinate relative to this objects location.
dy - y-coordinate relative to this objects location.
cls - Class of objects to look for (passing 'null' will find all objects).

getObjectsInRange

protected java.util.List getObjectsInRange(int r,
                                           java.lang.Class cls)
Return all objects within range 'r' around this object. An object is within range if the distance between its centre and this object's centre is less than or equal to r.

Parameters:
r - Radius of the cirle (in pixels)
cls - Class of objects to look for (passing 'null' will find all objects).

getOneIntersectingObject

protected Actor getOneIntersectingObject(java.lang.Class cls)
Return an object that intersects this object. This takes the graphical extent of objects into consideration.
NOTE: Does not take rotation into consideration.

Parameters:
cls - Class of objects to look for (passing 'null' will find all objects).

getOneObjectAtOffset

protected Actor getOneObjectAtOffset(int dx,
                                     int dy,
                                     java.lang.Class cls)
Return one object that is located at the specified cell (relative to this objects 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.

Parameters:
dx - X-coordinate relative to this objects location.
dy - y-coordinate relative to this objects 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.

getRObject

static rmiextension.wrappers.RObject getRObject(java.lang.Object obj)
                                         throws bluej.extensions.ProjectNotOpenException,
                                                bluej.extensions.PackageNotFoundException,
                                                java.rmi.RemoteException,
                                                bluej.extensions.ClassNotFoundException
Gets the remote reference to the obj.

IMPORTANT: This code is duplicated in greenfoot.World!

Throws:
bluej.extensions.ClassNotFoundException
java.rmi.RemoteException
bluej.extensions.PackageNotFoundException
bluej.extensions.ProjectNotOpenException

getRotation

public int getRotation()
Return the current rotation of the object. Rotation is expressed as a degree value, range (0..359). Zero degrees is to the east. The angle increases clockwise.

Returns:
The rotation in degrees.
See Also:
setRotation(int)

getWidth

public int getWidth()
Return the width of the object. The width is the number of cells that an object's image overlaps horizontally.

Returns:
The width of the object, or -1 if it has no image.
Throws:
java.lang.IllegalStateException - If there is no world instantiated.

getWorld

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

Returns:
The world.

getX

public int getX()
         throws java.lang.IllegalStateException
Return the x-coordinate of the object's current location. The value returned is the horizontal index of the object'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.

getY

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

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

intersects

protected boolean intersects(Actor other)
Check whether this object intersects with another given object. NOTE: Does not take rotation into consideration.

Returns:
True if the object's intersect, false otherwise.

isUsingClassImage

boolean isUsingClassImage()
Check whether the object is using the class image. This is true until getImage() is called, when a copy of the image is made. (package-private method).


setData

void setData(java.lang.Object o)

setImage

public void setImage(greenfoot.GreenfootImage image)
Set the image for this object to the specified image.

Parameters:
image - The image.
See Also:
setImage(String)

setImage

public void setImage(java.lang.String filename)
              throws java.lang.IllegalArgumentException
Set an image for this object from an image file. The file may be in jpeg, gif or png format. The file should be located in the project directory.

Parameters:
filename - The name of the image file.
Throws:
java.lang.IllegalArgumentException - If the image can not be loaded.

setLocation

public void setLocation(int x,
                        int y)
Assign a new location for this object. The location is specified as a cell index in the world. If this method is overridden it is important to call this method with super.setLocation(x,y) from the overriding method.

Parameters:
x - Location index on the x-axis
y - Location index on the y-axis
Throws:
java.lang.IllegalStateException - If the actor has not been added into a world.

setLocationInPixels

void setLocationInPixels(int x,
                         int y)
Translates the given location into cell-coordinates before setting the location. Used by the WorldHandler to drag objects.

Parameters:
x - x-coordinate in pixels
y - y-coordinate in pixels

setRotation

public void setRotation(int rotation)
Set the rotation of the object. Rotation is expressed as a degree value, range (0..359). Zero degrees is to the east. The angle increases clockwise.

Parameters:
rotation - The rotation in degrees.

setWorld

void setWorld(greenfoot.World world)
Sets the world of this actor.

Parameters:
world -