galapagos
Class Turtle

java.lang.Object
  extended by galapagos.Turtle
All Implemented Interfaces:
DrawingController, java.lang.Runnable

public class Turtle
extends java.lang.Object
implements DrawingController, java.lang.Runnable

This Turtle draws geometric shapes a DrawingCanvas. This turtle will run in a separate Thread so multiple turtles can be drawing on a single canvas. Date Modified: February, 2009 Made the class up-to-date Java 5.0 and cleaned up the code a bit.

Author:
Dr Caffeine

Field Summary
static int CREATE_DEFAULT_WINDOW
          Constant for creating a default drawing window
private  double currentOrientation
          This turtle's current orientation.
private  Position currentPosition
          This turtle's current position in the logical coordinate
private  int currentSpeed
          This turtle's current speed
private static java.awt.Color DEFAULT_COLOR
          Default color used in drawing
private static double DEFAULT_PENSIZE
          Default pen size used in drawing
private static int DEFAULT_SPEED
          Default speed of this turtle; unit is logical units/sec
private  boolean inMotion
          The motion flag: true makes turtle moving immediately after receiving command; otherwise the turtle is in the pause mode and will not move until told to move
private  java.util.Vector<TurtleCommand> instructionBuffer
          This turtle's instruction buffer to store user commands.
private  java.util.Vector<TurtleCommand> memory
          This turtle's memory to remember the past commands.
private  DrawingCanvas myCanvas
          The DrawingCanvas which this turtle is drawing its trajectory.
private  java.awt.Graphics myGraphics
          The Graphics object returned from the connected DrawingCanvas.
private  TurtleShape myShape
          The shape of this turtle to draw on the canvas.
static int NO_DEFAULT_WINDOW
          Constant for not creating any default drawing window
private static int PEN_DOWN
          Constant for pen down state.
private static int PEN_UP
          Constant for pen up state
private  java.awt.Color penColor
          This turtle's pen color
private  double penSize
          The pen size of this turtle in logical units
private  int penState
          The position (down or up) of this turtle's pen
private  TurtleDrawingWindow playGround
          Default drawing window for this turtle.
private  double redrawCurrentOrientation
          The orientation of this turtle during the redrawing phase
private  Position redrawCurrentPosition
          The position of this turtle during the redrawing phase.
private  boolean showBody
          The visibility flag: true makes turtle visible; otherwise invisible.
private static int STEP_INCR
          Number of logical units this turtle moves in one drawing
 
Constructor Summary
Turtle()
          A default constructor that creates an instance of the Turtle class with a default drawing window.
Turtle(int choice)
          Constructs a standard turtle with or without default drawing window assigned.
 
Method Summary
 void backup(double length)
          Moves this turtle backward for a specified length.
 void bodyColor(java.awt.Color color)
          Changes the body color of this turtle.
 void bodyShape(java.awt.Point[] point)
          Sets the shape of this turtle to the give shape expressed in an array of Point objects.
(package private)  void changeOrientation(double orientation)
          Sets the orientation of this turtle.
(package private)  void changePenColor(java.awt.Color color)
          Sets the pen color to the specified color.
(package private)  void changePenSize(float size)
          Sets the pen size to the specified size.
(package private)  void changePenState(int penState)
          Sets the pen position of this turtle, true for pen down and false for pen up.
(package private)  void changePosition(Position newLocation)
          Sets the current position of this turtle.
(package private)  void changeRedrawOrientation(double orientation)
          Changes the orientation of the turtle when redrawing the commands in the 'memory' Vector
(package private)  void changeRedrawPosition(Position position)
          Changes the position of the turtle while commands in the 'memory' vector are being executed.
(package private)  void changeSpeed(int speed)
          Changes the speed of this turtle to the designated speed.
(package private)  void changeVisibility(boolean status)
          Change the visibility of the Turtle body.
(package private)  void draw(double length)
          Draws this turtle's trajectory for a specified length.
(package private)  void drawShape(double orientation)
          Draw the turtle shape facing the given orientation
(package private)  void drawText(java.lang.String text)
          Draws the specified text at the current position of the turtle.
(package private)  void drawTextMemory(java.lang.String text, Position position)
          Draws text specified by the DrawTextCommand command in the memory
 void forward(double length)
          Moves this turtle forward for a given length.
 void heading(double degree)
          Sets this turtle's heading for a specified degree.
 void hide()
          Hides this turtle, that is, the turtle body is not displayed..
 void init()
          Initializes this turtle.
private  void initMemory()
          Clears this turtle's memory.
 void jumpTo(double x, double y)
          Jumps to the given (x, y).
 void move(double length)
          Moves this turtle's for a specified length.
 void moveTo(double targetX, double targetY)
          Moves this turtle to the specified target (x, y) position.
 void pause()
          Stops this turtle from moving.
 void penColor(java.awt.Color color)
          Sets the color of the turtle's pen.
 void penDown()
          Sets the pen state to down.
 void penSize(int penSize)
          Sets the size of this turtle's pen.
 void penUp()
          Sets the pen state to up.
(package private)  void plot(Position target, int penState, java.awt.Color penColor, double penSize)
          If the pen is down, this method calls the DrawingCanvas plot method to draw a line between redrawCurrentPosition to target in the specified color and pen size.
 void print(java.lang.String message)
          Prints the specified message at the current position.
 void redraw(java.awt.Graphics g)
          Required method to implement the DrawingController interface.
private  void reset()
          Resets this turtle to it's initial state
(package private)  void rotate(double degree)
          Turns this turtle's orientation for a specified degree in counter clockwise direction.
 void run()
          Required method to implement the Runnable interface.
 void setCanvas(DrawingCanvas canvas)
          Required method to implement the DrawingController interface.
 void show()
          Shows this turtle, that is, the turtle body is displayed.
 void speed(int speed)
          Changes the speed of this turtle
 void start()
          Starts moving this turtle in its own thread.
private  void startRunning()
          Starts this turtle running in its own thread.
 void turn(double degree)
          Turns the turtle
(package private)  void turnAndMove(Position target)
          Implements the MoveTo command by using the changeOrientation and draw methods.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CREATE_DEFAULT_WINDOW

public static final int CREATE_DEFAULT_WINDOW
Constant for creating a default drawing window

See Also:
Constant Field Values

NO_DEFAULT_WINDOW

public static final int NO_DEFAULT_WINDOW
Constant for not creating any default drawing window

See Also:
Constant Field Values

PEN_DOWN

private static final int PEN_DOWN
Constant for pen down state.

See Also:
Constant Field Values

PEN_UP

private static final int PEN_UP
Constant for pen up state

See Also:
Constant Field Values

DEFAULT_SPEED

private static final int DEFAULT_SPEED
Default speed of this turtle; unit is logical units/sec

See Also:
Constant Field Values

DEFAULT_PENSIZE

private static final double DEFAULT_PENSIZE
Default pen size used in drawing

See Also:
Constant Field Values

DEFAULT_COLOR

private static final java.awt.Color DEFAULT_COLOR
Default color used in drawing


STEP_INCR

private static final int STEP_INCR
Number of logical units this turtle moves in one drawing

See Also:
Constant Field Values

penState

private int penState
The position (down or up) of this turtle's pen


penSize

private double penSize
The pen size of this turtle in logical units


penColor

private java.awt.Color penColor
This turtle's pen color


currentPosition

private Position currentPosition
This turtle's current position in the logical coordinate


currentOrientation

private double currentOrientation
This turtle's current orientation.


currentSpeed

private int currentSpeed
This turtle's current speed


myGraphics

private java.awt.Graphics myGraphics
The Graphics object returned from the connected DrawingCanvas. This Graphics object is used by this turtle to draw its trajectory.


myCanvas

private DrawingCanvas myCanvas
The DrawingCanvas which this turtle is drawing its trajectory.


redrawCurrentPosition

private Position redrawCurrentPosition
The position of this turtle during the redrawing phase.


redrawCurrentOrientation

private double redrawCurrentOrientation
The orientation of this turtle during the redrawing phase


memory

private java.util.Vector<TurtleCommand> memory
This turtle's memory to remember the past commands. Once the command gets stored in memory, it'll stay there forever. The purpose is to redraw the frame when redrawing of the content is necessary


instructionBuffer

private java.util.Vector<TurtleCommand> instructionBuffer
This turtle's instruction buffer to store user commands. This is a queue. As long as the queue is not empty, we continue removing the first (head) command in the queue and executing it. A new command is added to the tail.


myShape

private TurtleShape myShape
The shape of this turtle to draw on the canvas.


showBody

private boolean showBody
The visibility flag: true makes turtle visible; otherwise invisible.


inMotion

private boolean inMotion
The motion flag: true makes turtle moving immediately after receiving command; otherwise the turtle is in the pause mode and will not move until told to move


playGround

private TurtleDrawingWindow playGround
Default drawing window for this turtle. When this turtle is added explicitly to another drawing canvas, then this drawing window is ignored.

Constructor Detail

Turtle

public Turtle()
A default constructor that creates an instance of the Turtle class with a default drawing window. The orientation of this turtle is 0 degree, i.e., facing East where the top of the screen is North. The pen is down with its color black and pen size 2 logical units wide.


Turtle

public Turtle(int choice)
Constructs a standard turtle with or without default drawing window assigned. The orientation of this turtle is 0 degree, i.e., facing East where the top of the screen is North. The pen is down with its color black and pen size 2 logical units wide.

Parameters:
choice - zero means no default window; non-zero will create a default window
Method Detail

backup

public void backup(double length)
Moves this turtle backward for a specified length.

Parameters:
length - the length to move backward

bodyColor

public void bodyColor(java.awt.Color color)
Changes the body color of this turtle. You cannot change the body color while the turtle is moving. Basically you want to set the turtle's body color once.

Parameters:
color - a new body color

bodyShape

public void bodyShape(java.awt.Point[] point)
Sets the shape of this turtle to the give shape expressed in an array of Point objects. The shape can be any polygon. You cannot change the body shape while the turtle is moving. Basically you want to set the turtle's body shape once.

Parameters:
point - an array of Point objects representing a polygon

forward

public void forward(double length)
Moves this turtle forward for a given length. This method is the same as the move method with a positive argument.

Parameters:
length - the length to move forward

heading

public void heading(double degree)
Sets this turtle's heading for a specified degree. The current heading is irrelevant. If the specified degree is negative, then it is a clockwise direction

Parameters:
degree - the new orientation of this turtle

hide

public void hide()
Hides this turtle, that is, the turtle body is not displayed..


init

public void init()
Initializes this turtle. When a turtle is first created, it is initialized automatically. The user needs to call this method explicitly, when a new drawing is required by the same turtle.


jumpTo

public void jumpTo(double x,
                   double y)
Jumps to the given (x, y). This is a warp jump so no drawing will take place, even when the pen is down.

Parameters:
x - the x coordinate of the target position
y - the y coordinate of the target position

move

public void move(double length)
Moves this turtle's for a specified length. Positive length moves the turtle forward and the negative length moves the turtle backward relative to its orientation. The position of this turtle is set to the new location. The orientation remains the same.


moveTo

public void moveTo(double targetX,
                   double targetY)
Moves this turtle to the specified target (x, y) position. The turtle's orientation will be adjusted to face the the target (x,y) position, regardless where this turtle is facing before this method is called.

Parameters:
targetX - the x coordinate of the target point
targetY - the y coordinate of the target point

pause

public void pause()
Stops this turtle from moving. Once in the pause mode this turtle needs to be activated by calling the start method. Otherwise the turtle will never move again.


penColor

public void penColor(java.awt.Color color)
Sets the color of the turtle's pen.

Parameters:
color - a new pen color for subsequent drawing

penDown

public void penDown()
Sets the pen state to down. Subsequent movement by this turtle will result in drawing the line.


penSize

public void penSize(int penSize)
Sets the size of this turtle's pen.

Parameters:
penSize - the new pen size

penUp

public void penUp()
Sets the pen state to up. Subsequent movement by this turtle will not result in drawing the line, i.e., this turtle moves to a specified location without drawing.


print

public void print(java.lang.String message)
Prints the specified message at the current position. The color of text is fixed to black. You cannot change the text color.

Parameters:
message - the text to display

redraw

public void redraw(java.awt.Graphics g)
Required method to implement the DrawingController interface. Redraws the shape currently drawn by the turtle. This method is called from DrawingCanvas when the repaint method is invoked by the system. Do not call this method directly from your code.

Specified by:
redraw in interface DrawingController
Parameters:
g - the Graphics object where this turtle can draw

run

public void run()
Required method to implement the Runnable interface. This method is called eventually by the system, and when called, will execute the commands in the instruction buffer provided that this turtle is in the motion mode (i.e. the pause method is not called).

Specified by:
run in interface java.lang.Runnable

setCanvas

public void setCanvas(DrawingCanvas canvas)
Required method to implement the DrawingController interface. This method is called by a DrawingCanvas object. Do not call this method directly from your code.

Specified by:
setCanvas in interface DrawingController
Parameters:
canvas - the object that called this method

show

public void show()
Shows this turtle, that is, the turtle body is displayed.


speed

public void speed(int speed)
Changes the speed of this turtle

Parameters:
speed - the new speed of this turtle

start

public void start()
Starts moving this turtle in its own thread.


turn

public void turn(double degree)
Turns the turtle


changeOrientation

void changeOrientation(double orientation)
Sets the orientation of this turtle.

Parameters:
orientation - the direction of this turtle's heading

changePenColor

void changePenColor(java.awt.Color color)
Sets the pen color to the specified color.

Parameters:
color - the new color

changePenSize

void changePenSize(float size)
Sets the pen size to the specified size.

Parameters:
size - the new pen size

changePenState

void changePenState(int penState)
Sets the pen position of this turtle, true for pen down and false for pen up.

Parameters:
penState - either Turtle.PEN_DOWN or Turtle.PEN_UP

changePosition

void changePosition(Position newLocation)
Sets the current position of this turtle. Calling the method has the effect of a turtle warping to a new position instantaneously. No drawing will occur even if the pen is down.

Parameters:
newLocation - the new location of this turtle

changeRedrawOrientation

void changeRedrawOrientation(double orientation)
Changes the orientation of the turtle when redrawing the commands in the 'memory' Vector

Parameters:
orientation - the new orientation of this turtle

changeRedrawPosition

void changeRedrawPosition(Position position)
Changes the position of the turtle while commands in the 'memory' vector are being executed.

Parameters:
position - the new position

changeSpeed

void changeSpeed(int speed)
Changes the speed of this turtle to the designated speed.

Parameters:
speed - the new moving speed of this turtle

changeVisibility

void changeVisibility(boolean status)
Change the visibility of the Turtle body.

Parameters:
status - true to show Turtle body; false to hide the body

draw

void draw(double length)
Draws this turtle's trajectory for a specified length. Positive length moves the turtle forward and the negative length moves the turtle backward relative to its orientation. The position of this turtle is set to the new location. The orientation remains the same.


drawShape

void drawShape(double orientation)
Draw the turtle shape facing the given orientation


drawText

void drawText(java.lang.String text)
Draws the specified text at the current position of the turtle.

Parameters:
text -

drawTextMemory

void drawTextMemory(java.lang.String text,
                    Position position)
Draws text specified by the DrawTextCommand command in the memory

Parameters:
text - the text to display
position - the position on the canvas to display the text

plot

void plot(Position target,
          int penState,
          java.awt.Color penColor,
          double penSize)
If the pen is down, this method calls the DrawingCanvas plot method to draw a line between redrawCurrentPosition to target in the specified color and pen size.

Parameters:
target - the next starting position for redrawing.
penState - the state of the pen (UP or DOWN).
penColor - the pen color.
penSize - the thickness of the pen.

rotate

void rotate(double degree)
Turns this turtle's orientation for a specified degree in counter clockwise direction. If the specified degree is negative, then it is a clockwise direction

Parameters:
degree - the amount of degree this turtle rotates from the current orientation

turnAndMove

void turnAndMove(Position target)
Implements the MoveTo command by using the changeOrientation and draw methods.

Parameters:
target - a target position this turtle moves to from its current position.

initMemory

private void initMemory()
Clears this turtle's memory.


reset

private void reset()
Resets this turtle to it's initial state


startRunning

private void startRunning()
Starts this turtle running in its own thread.