com.otherwise.jurtle
Class Turtle

java.lang.Object
  extended bycom.otherwise.jurtle.Turtle
All Implemented Interfaces:
java.lang.Runnable

public abstract class Turtle
extends java.lang.Object
implements java.lang.Runnable

The Turtle class is an abstract class you extend to give your turtle its specific behavior. You do this by implementing the runTurtle() method, and in this method call other various Turtle methods to have it move and draw on the screen. This runTurtle() method is automatically called by Jurtle when you run the Turtle.

If the Turtle implements a public static main(String[] args), method, it will be called first instead of runTurtle(). The main method is then responsible for instantiating the turtle (or turtles) and calling its start() method. The call to start() will then result in runTurtle being called.


Field Summary
static int NO_PAUSE
          Constant that can be passed to pause() or setAutoUpdatePause() to indicate there should be no actual pause.
 
Constructor Summary
Turtle()
          Basic Turtle constructor.
Turtle(java.awt.Color penColor, int penWidth, double heading, double x, double y)
          Turtle constructor that allows you to specify the initial penColor, penWidth, heading and position.
 
Method Summary
 void backward(double distance)
          Move the turtle backward the specified distance.
 void center()
          Center the turtle in the display pane.
 void clearDisplay()
          Clears the display, leaving the turtle where it is.
 void forward(double distance)
          Move the turtle forward the specified distance.
 boolean getAutoUpdate()
          Gets the current value of the autoUpdate flag.
 long getAutoUpdatePause()
          Gets the autoUpdate pause value.
 javax.swing.JPanel getDisplay()
          Returns the JPanel used for the Turtle's display area.
 java.awt.Color getDisplayColor()
          Returns the display's background color.
 java.awt.Container getDisplayContainer()
          Returns the Container that contains the Turtle's display area.
 java.awt.Dimension getDisplaySize()
          Return the size of the turtle's display pane.
 java.awt.Graphics getGraphics()
          Return the turtle's graphics context.
 double getHeading()
          Return the turtle's heading.
 java.awt.Color getPenColor()
           
 int getPenWidth()
          Returns the turtle's penWidth.
 java.awt.Color getPixelColor(int x, int y)
          Returns the color of the pixel at the specified point in the display's coordinate system (0,0 is at the upper left of the display).
 java.awt.Point getPosition()
          Return the current position of the turtle.
 java.util.Enumeration getTurtles()
          Returns an Enumeration of all the current turtles.
 void hideTurtle()
          Hide the turtle so it will not be seen while drawing.
 void home()
          Return the turtle to its default (home) state.
 boolean isPenDown()
          Returns whether the pen is currently down.
 boolean isRunning()
          Gets the turtle's running status.
 boolean isVisible()
          Determine if the turtle is visible.
 void left(double degrees)
          Rotate the turtle to the left (counterclockwise).
 void paintTurtle(java.awt.Graphics g)
          Called to have the turtle paint itself.
 void pause(long pauseMillis)
          Pauses the turtle's execution for pauseMillis milliseconds.
 void penDown()
          Put the turtle's pen back down so it will draw when moving.
 void penErase()
          Change the pen to an eraser.
 void penPaint()
          Return the drawing version of the pen after erasing.
 void penUp()
          Lift the turtle's pen so it doesn't draw when moving
 void right(double degrees)
          Rotate the turtle to the right (clockwise).
 void run()
          Called by start() to begin running the turtle's thread.
abstract  void runTurtle()
          Called to execute the turtle code in a separate thread.
 void setAutoUpdate(boolean autoUpdate)
          Sets a flag indicating whether to automatically update the display after each turtle command that affects it.
 void setAutoUpdatePause(long pauseMillis)
          Sets the number of milliseconds the system pauses after performing an automatic update.
 void setDisplayColor(java.awt.Color color)
          Set the display's background color.
 void setHeading(double heading)
          Set the direction the turtle is pointing in.
 void setPenColor(java.awt.Color color)
          Set the pen color for the trail the turtle leaves.
 void setPenWidth(int width)
          Set the pen width for the trail the turtle leaves.
 void setPixelColor(int x, int y, java.awt.Color color)
          Sets the color of the pixel at the specified point in the display's coordinate system (0,0 is at the upper left of the display).
 void setPosition(double newX, double newY)
          Move the turtle to the specified coordinates.
 void setPositionX(double newX)
          Move the turtle to the new x coordinate leaving the y coordinate unchanged.
 void setPositionY(double newY)
          Move the turtle to the new y coordinate leaving the x coordinate unchanged.
 void showTurtle()
          Shows the turtle, making it visible.
 void start()
          Called to start running the turtle in its own thread of execution.
 void stopTurtle()
          Stops the turtle's execution.
 void turtleStopped()
          Called by Jurtle when the turtle has been stopped.
 void updateDisplay()
          Update the display with any turtle drawing.
 void waitForStop()
          Causes the turtle's thread to sleep and wait for either stopTurtle() to be called or Stop command to be invoked from Jurtle's GUI.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NO_PAUSE

public static final int NO_PAUSE
Constant that can be passed to pause() or setAutoUpdatePause() to indicate there should be no actual pause.

See Also:
Constant Field Values
Constructor Detail

Turtle

public Turtle()
Basic Turtle constructor. Creates a new Turtle with:


Turtle

public Turtle(java.awt.Color penColor,
              int penWidth,
              double heading,
              double x,
              double y)
Turtle constructor that allows you to specify the initial penColor, penWidth, heading and position.

Method Detail

backward

public void backward(double distance)
Move the turtle backward the specified distance. If the pen is down, the turtle will leave a trail. The turtles heading is not changed.

Parameters:
distance - the distance to move the turtle.

center

public void center()
Center the turtle in the display pane. No drawing occurs, even if the pen is down.


clearDisplay

public void clearDisplay()
Clears the display, leaving the turtle where it is.


forward

public void forward(double distance)
Move the turtle forward the specified distance. If the pen is down the turtle will leave a trail.

Parameters:
distance - the distance to move the turtle.

getAutoUpdate

public boolean getAutoUpdate()
Gets the current value of the autoUpdate flag.

Returns:
the autoUpdate's flag value.
See Also:
setAutoUpdate(boolean)

getAutoUpdatePause

public long getAutoUpdatePause()
Gets the autoUpdate pause value.

Returns:
The number of milliseconds the turtle pauses for after automatically updateing the diaplay.
See Also:
setAutoUpdate(boolean)

getDisplay

public javax.swing.JPanel getDisplay()
Returns the JPanel used for the Turtle's display area. You should not add components to the Display. If you want to add controls for the Turtle, you should use getDisplayContainer() and add them there.


getDisplayContainer

public java.awt.Container getDisplayContainer()
Returns the Container that contains the Turtle's display area. You may add components to this Container or change its layout manager if desired. One use of this is to add components that control the Turtle's behavior (e.g. a JSlider that controls the turning angle of the Turtle).


getDisplayColor

public java.awt.Color getDisplayColor()
Returns the display's background color. This color is white by default but make be changed with setDisplayColor().

Returns:
the display's background color.
See Also:
setDisplayColor(java.awt.Color)

getDisplaySize

public java.awt.Dimension getDisplaySize()
Return the size of the turtle's display pane.

Returns:
Dimension holding the size.

getGraphics

public java.awt.Graphics getGraphics()
Return the turtle's graphics context. This may be used to do drawing in the display pane other than what the turtle directly supports. In order to prevent a deadlock that will freeze Jurtle, you must synchronize on the Graphics object during the drawing. For example:

Graphic g = getGraphics();
synchronized( g )
{
    g.fillRect(100, 100, 20, 20);
}


getHeading

public double getHeading()
Return the turtle's heading.


getPenColor

public java.awt.Color getPenColor()

isPenDown

public boolean isPenDown()
Returns whether the pen is currently down.


getPenWidth

public int getPenWidth()
Returns the turtle's penWidth.


getPixelColor

public java.awt.Color getPixelColor(int x,
                                    int y)
Returns the color of the pixel at the specified point in the display's coordinate system (0,0 is at the upper left of the display).

Returns:
Color at the specified point

getPosition

public java.awt.Point getPosition()
Return the current position of the turtle.

Returns:
Point the current position of the turtle.

getTurtles

public java.util.Enumeration getTurtles()
Returns an Enumeration of all the current turtles.


hideTurtle

public void hideTurtle()
Hide the turtle so it will not be seen while drawing.


home

public void home()
Return the turtle to its default (home) state. The following commands are executed: center(); setPenColor(Color.black); setHeading(0); showTurtle(); penDown();


isRunning

public boolean isRunning()
Gets the turtle's running status. A turtle is running if it has beee started and its runTurtle() hasn't completed.

Returns:
true if turtle is running; otherwise, false

isVisible

public boolean isVisible()
Determine if the turtle is visible. Note: "visible" means the triangular representation of the turtle will be drawn on the display. To control whether the turtle leaves a trail when moving use setPenDown().

Returns:
true if turtle is visible; otherwise, false

left

public void left(double degrees)
Rotate the turtle to the left (counterclockwise).

Parameters:
degrees - the number of degrees to rotate the turtle.

paintTurtle

public void paintTurtle(java.awt.Graphics g)
Called to have the turtle paint itself. The default implementation draws the turtle as a triangle. You may override the method to draw the turtle in some other way.

Parameters:
g - the Graphics object to use for drawing.

pause

public void pause(long pauseMillis)
Pauses the turtle's execution for pauseMillis milliseconds. If pauseMillis is 0 or less, no pause will happen.


penDown

public void penDown()
Put the turtle's pen back down so it will draw when moving.


penErase

public void penErase()
Change the pen to an eraser.


penPaint

public void penPaint()
Return the drawing version of the pen after erasing.


penUp

public void penUp()
Lift the turtle's pen so it doesn't draw when moving


right

public void right(double degrees)
Rotate the turtle to the right (clockwise).

Parameters:
degrees - the number of degrees to rotate the turtle.

run

public void run()
Called by start() to begin running the turtle's thread. You should never need to call this method directly.

Specified by:
run in interface java.lang.Runnable

runTurtle

public abstract void runTurtle()
Called to execute the turtle code in a separate thread. Subclasses must implement this method in order to draw on the display.


setAutoUpdate

public void setAutoUpdate(boolean autoUpdate)
Sets a flag indicating whether to automatically update the display after each turtle command that affects it. The default is true. Note: in cases where you want to speed up code execution yet still see some intermediate results, you can set autoUpdate to false and periodically call updateDisplay() at places where you want the drawing displayed on the display.

Parameters:
autoUpdate - a boolean flag indicating whether to turn automatic display on or off.

setAutoUpdatePause

public void setAutoUpdatePause(long pauseMillis)
Sets the number of milliseconds the system pauses after performing an automatic update. The default is 0. If setAutoUpdate(true) has been called to turn on automatic updating, then after each display update, the turtle will pause for pauseMillis milliseconds. This is useful to see the individual drawing operations.

Parameters:
pauseMillis - number of milliseconds to automatically pause after drawing commands.

setDisplayColor

public void setDisplayColor(java.awt.Color color)
Set the display's background color. This command will erase any existing drawing on the display.


setHeading

public void setHeading(double heading)
Set the direction the turtle is pointing in.

Parameters:
heading - the direction to point the turtle. 0 degrees is North and 90 is East.

setPenColor

public void setPenColor(java.awt.Color color)
Set the pen color for the trail the turtle leaves.

Parameters:
color - the color to set the pen to.

setPenWidth

public void setPenWidth(int width)
Set the pen width for the trail the turtle leaves. The default width is 1 pixel.

Parameters:
width - the width to set the pen to.

setPixelColor

public void setPixelColor(int x,
                          int y,
                          java.awt.Color color)
Sets the color of the pixel at the specified point in the display's coordinate system (0,0 is at the upper left of the display).

Parameters:
x - x-coordinate of pixel
y - y-coordinate of pixel
color - color to set pixel at the specified point

setPosition

public void setPosition(double newX,
                        double newY)
Move the turtle to the specified coordinates. If the pen is currently down then it leaves a trail.

Parameters:
newX - new x coordinate
newY - new y coordinate

setPositionX

public void setPositionX(double newX)
Move the turtle to the new x coordinate leaving the y coordinate unchanged. If the pen is currently down, it leaves a trail.

Parameters:
newX - new x coordinate

setPositionY

public void setPositionY(double newY)
Move the turtle to the new y coordinate leaving the x coordinate unchanged. If the pen is currently down, it leaves a trail.

Parameters:
newY - new y coordinate

showTurtle

public void showTurtle()
Shows the turtle, making it visible.


start

public void start()
Called to start running the turtle in its own thread of execution. Calling start() results in the turtle's runTurtle() method being called.


stopTurtle

public void stopTurtle()
Stops the turtle's execution. Normally a turtle's execution is stopped by just letting the runTurtle() method exit. However if you called waitForStop() at the end of the runTurtle() method, stopTurtle may be call to end execution.


turtleStopped

public void turtleStopped()
Called by Jurtle when the turtle has been stopped. You never call this method yourself. You can override it if you need to do some clean up when the turtle stops. If overridden, remember to call super.turtleStopped() to give the superclass a chance to clean up.


updateDisplay

public void updateDisplay()
Update the display with any turtle drawing.


waitForStop

public void waitForStop()
Causes the turtle's thread to sleep and wait for either stopTurtle() to be called or Stop command to be invoked from Jurtle's GUI. This method should be called if your code creates any GUI elements and then would normally exit. Call this method after creating the GUI and it will keep the main turtle thread alive.