objectdraw
Class Turtle

java.lang.Object
  extended by objectdraw.ObjectDrawObject
      extended by objectdraw.ObjectDrawShape
          extended by objectdraw.Turtle
All Implemented Interfaces:
objectdraw.Dependent, DrawableInterface, DrawableStrokeInterface, LocatableInterface

public class Turtle
extends objectdraw.ObjectDrawShape
implements DrawableStrokeInterface, LocatableInterface

A Turtle object allows you to draw lines and filled-in polygons by giving instructions to a computer creature called a "turtle" that moves around on the screen and draws a line as it goes. The instructions are of the form "move forward this far" or "turn right this many degrees". Often it is easier to draw graphics this way than it is to try to figure out the coordinates of all the points involved. So, for example, I can draw a pentagon without needing any trigonometry, because all it takes to walk out a pentagon is to move forward, turn right 72°, and repeat that five times. If I want to fill in that pentagon, all I need to do is to tell the turtle to beginFill() when it starts drawing, and then to close() the shape and endFill() when it is done.

Once a turtle has completed its sketch, you can move that sketch around and resize it just as you would any object on the canvas. You can also rotate a turtle sketch. Resizing and rotating are centered around the point at which the turtle was located when it was first created.

Because the sketch may contain many different colors - I can change the pen color as I move, and each fill area has its own color - the setColor() method would not work to recolor the sketch after it is done. Instead, there is a method recolorSketch() that can be used to take all parts of the sketch that were originally in a particular color, and change them to another color.

Author:
Russell Zahniser (russell@zahniser.net)

Field Summary
 
Fields inherited from interface objectdraw.DrawableStrokeInterface
CLICK_SIZE, DEFAULT_STROKE
 
Constructor Summary
Turtle(Color color, DrawingCanvas canvas)
          Construct a Turtle at the center of canvas, facing to the right, and drawing a line in the given color.
Turtle(double x, double y, Color color, DrawingCanvas canvas)
          Construct a Turtle at (x, y), facing to the right, and drawing a line in the given color.
Turtle(double x, double y, DrawingCanvas canvas)
          Construct a Turtle at (x, y), facing to the right, and drawing a line in black.
Turtle(DrawingCanvas canvas)
          Construct a Turtle at the center of canvas, facing to the right, and drawing a line in black.
Turtle(Location start, Color color, DrawingCanvas canvas)
          Construct a Turtle at start, facing to the right, and drawing a line in the given color.
Turtle(Location start, DrawingCanvas canvas)
          Construct a Turtle at start, facing to the right, and drawing a line in the given color.
Turtle(Turtle clone, DrawingCanvas canvas)
          Construct a clone of clone and place it on the given canvas.
 
Method Summary
 void addToCanvas(DrawingCanvas c)
          Place this object on the specified canvas.
 void beginFill(Color fillColor)
          Tell this turtle to begin outlining a shape that will be filled in with fillColor.
 void clearSketch()
          Clear this turtle's sketch.
 void close()
          Close the shape that the turtle is currently drawing by connecting a line back to the starting point.
 boolean contains(Location point)
          Return true if the given location is inside this object, false otherwise.
 void endFill()
          Finish up the fill region you are currently working on, and go back to adding to the previously active fill region, if there is one.
 DrawingCanvas getCanvas()
          Return the canvas that this object is on.
 Color getColor()
          Return the color of this object
 double getDoubleX()
          Get this object's x coordinate, in double precision.
 double getDoubleY()
          Get this object's y coordinate, in double precision.
 double getHeading()
          Get the turtle's heading - the direction, as a degree angle, that it is facing.
 double getLineWidth()
          Return the width of this object's lines.
 Location getLocation()
          Get this object's location.
 double getSketchDoubleX()
          Get the x coordinate of the origin of the sketch, in double precision.
 double getSketchDoubleY()
          Get the y coordinate of the origin of the sketch, in double precision.
 Location getSketchLocation()
          Get the location of the origin of the sketch.
 double getSketchRotation()
          Get the angle of rotation of this turtle's sketch
 double getSketchScale()
          Get the scale factor of the sketch - the degree to which it has been shrunk or expanded.
 int getSketchX()
          Get the x coordinate of the origin of the sketch, in int precision.
 int getSketchY()
          Get the y coordinate of the origin of the sketch, in int precision.
 BasicStroke getStroke()
          Return the stroke used for this object's lines.
 int getX()
          Get this object's x coordinate.
 int getY()
          Get this object's y coordinate.
 void hide()
          Make this object invisible.
 void hideTurtle()
          A little triangle-shaped icon represents the turtle while it is drawing the sketch, to make it easier for you to see where the turtle is and which way it is facing when you are trying to figure out how to get it to draw a shape.
 boolean isHidden()
          Return true if this object has been rendered invisible with a call to its hide() method, false if it is still being drawn.
 boolean isPenDown()
          Determine whether the turtle is leaving a line behind as it moves
 boolean isTurtleHidden()
          Determine whether the turtle's icon is hidden
 void lt()
          Turn 90° to the left.
 void lt(double angle)
          Turn angle degrees to the left
 void move()
          Move forward 40 pixels
 void move(double distance)
          Move forward distance pixels
 void move(double dx, double dy)
          Shift (translate) this object left or right by an amount dx, and up or down by an amount dy.
 void moveSketch(double dx, double dy)
          Move the turtle and its entire sketch by the given amount in the x and y.
 void moveSketchTo(double x, double y)
          Move the origin on the sketch to (x, y).
 void moveSketchTo(Location point)
          Move the origin on the sketch to the given Location.
 void moveTo(double x, double y)
          Move the reference point of this object to the given location.
 void moveTo(Location point)
          Move the reference point of this object to the given location.
 void penDown()
          Tell the turtle to resume drawing a line behind it as it moves.
 void penUp()
          Tell the turtle to lift up its pen, so that it moves without drawing a line behind it.
 void recolorSketch(Color original, Color substitute)
          Replace all parts of the sketch that were drawn in the color original with the new color substitute.
 void removeFromCanvas()
          Remove this object from its canvas.
 void rotateSketch(double byAngle)
          Rotate this sketch by the given angle, in degrees.
 void rt()
          Turn 90° to the right.
 void rt(double angle)
          Turn angle degrees to the right
 void scaleSketch(double byFactor)
          Add a scale factor to this turtle's sketch, causing it to be shrunk or expanded.
 void sendBackward()
          Move this object one step backward in the draw order, causing it to be drawn underneath the objects that are in front of it.
 void sendForward()
          Move this object one step forward in the draw order, causing it to be drawn on top of the objects that are behind it.
 void sendToBack()
          Move this object to the very back of the draw order, causing it to be drawn underneath all the other objects.
 void sendToFront()
          Move this object to the very front of the draw order, causing it to be drawn on top of all the other objects.
 void setColor(Color c)
          Change the color of this object.
 void setHeading(double heading)
          Give the turtle a new heading
 void setLineWidth(double width)
          Set the width of this object's lines
 void setSketchRotation(double angle)
          Set the angle, in degrees, by which this sketch should be rotated.
 void setSketchScale(double factor)
          Set the scale factor of this turtle's sketch, causing it to be shrunk or expanded.
 void setStroke(BasicStroke stroke)
          Set the stroke used for this object's lines
 void show()
          Make an object visible again after it had been hidden.
 void showTurtle()
          Show the turtle icon again after it had been hidden
 String toString()
          Return a string describing how this object might be constructed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Turtle

public Turtle(Color color,
              DrawingCanvas canvas)
Construct a Turtle at the center of canvas, facing to the right, and drawing a line in the given color.

Parameters:
color - Color the turtle will be drawing in
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(double x,
              double y,
              Color color,
              DrawingCanvas canvas)
Construct a Turtle at (x, y), facing to the right, and drawing a line in the given color.

Parameters:
x - x coordinate of the turtle
y - y coordinate of the turtle
color - Color the turtle will be drawing in
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(double x,
              double y,
              DrawingCanvas canvas)
Construct a Turtle at (x, y), facing to the right, and drawing a line in black.

Parameters:
x - x coordinate of the turtle
y - y coordinate of the turtle
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(DrawingCanvas canvas)
Construct a Turtle at the center of canvas, facing to the right, and drawing a line in black.

Parameters:
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(Location start,
              Color color,
              DrawingCanvas canvas)
Construct a Turtle at start, facing to the right, and drawing a line in the given color.

Parameters:
start - the Location at which the turtle should be placed
color - Color the turtle will be drawing in
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(Location start,
              DrawingCanvas canvas)
Construct a Turtle at start, facing to the right, and drawing a line in the given color.

Parameters:
start - the Location at which the turtle should be placed
canvas - DrawingCanvas on which the turtle should be placed

Turtle

public Turtle(Turtle clone,
              DrawingCanvas canvas)
Construct a clone of clone and place it on the given canvas. This allows you to sketch a shape once with a single Turtle and then use that as a template to make more copies of that shape.

Parameters:
clone - Turtle to copy
canvas - DrawingCanvas on which the new turtle should be placed
Method Detail

addToCanvas

public void addToCanvas(DrawingCanvas c)
Place this object on the specified canvas. The object will be removed from its current canvas, if it is on a canvas that is not the one it is being moved to. The object will be at the front of the canvas, as if it had just been drawn. If the given canvas is null the object is simply removed from its current canvas.

Specified by:
addToCanvas in interface DrawableInterface
Overrides:
addToCanvas in class objectdraw.ObjectDrawShape
Parameters:
c - DrawingCanvas to place this object on

beginFill

public void beginFill(Color fillColor)
Tell this turtle to begin outlining a shape that will be filled in with fillColor. You should later call endFill() once the shape has been outlined. If a new fill region is started with another call to beginFill() before you call endFill(), the turtle will start adding to the new fill region instead and will make no changes to the previous fill region until the new one is ended.

Parameters:
fillColor - Color to fill in with

clearSketch

public void clearSketch()
Clear this turtle's sketch. All its lines and fills will be deleted. The turtle remains at its current position.


close

public void close()
Close the shape that the turtle is currently drawing by connecting a line back to the starting point. The starting point may not be the original starting point of the turtle; a new "path" is started when you change the line color or stroke.


contains

public boolean contains(Location point)
Return true if the given location is inside this object, false otherwise. Because Lines and FramedArcs have no "inside", a point is considered to be contained in one of them as long as it is within a few pixels of the line.

Specified by:
contains in interface DrawableInterface
Parameters:
point - Location to test
Returns:
whether the given location is inside this shape

endFill

public void endFill()
Finish up the fill region you are currently working on, and go back to adding to the previously active fill region, if there is one.


getCanvas

public DrawingCanvas getCanvas()
Return the canvas that this object is on. If it has been removed from its canvas, this method will return null.

Specified by:
getCanvas in interface DrawableInterface
Overrides:
getCanvas in class objectdraw.ObjectDrawShape
Returns:
the DrawingCanvas that this object is on.

getColor

public Color getColor()
Return the color of this object

Specified by:
getColor in interface DrawableInterface
Overrides:
getColor in class objectdraw.ObjectDrawShape
Returns:
the Color of this object

getDoubleX

public double getDoubleX()
Get this object's x coordinate, in double precision.

Specified by:
getDoubleX in interface LocatableInterface
Returns:
this object's x coordinate, in double precision

getDoubleY

public double getDoubleY()
Get this object's y coordinate, in double precision.

Specified by:
getDoubleY in interface LocatableInterface
Returns:
this object's y coordinate, in double precision

getHeading

public double getHeading()
Get the turtle's heading - the direction, as a degree angle, that it is facing.

Returns:
the turtle's heading

getLineWidth

public double getLineWidth()
Return the width of this object's lines.

Specified by:
getLineWidth in interface DrawableStrokeInterface
Returns:
the width of this object's lines

getLocation

public Location getLocation()
Get this object's location. Translating this Location object will have the same effect as moving the object. So, the following two lines of code are equivalent:

object.move(10, 20);
object.getLocation().translate(10, 20);


If you want to create a Location offset by some amount from the Location of this object, without actually moving this object, use the offset() method in Location, which creates a new Location.

Specified by:
getLocation in interface LocatableInterface
Returns:
the Location of this object.

getSketchDoubleX

public double getSketchDoubleX()
Get the x coordinate of the origin of the sketch, in double precision. The origin is the point on the sketch where the turtle started out.

Returns:
the x coordinate of the origin of the sketch, in double precision

getSketchDoubleY

public double getSketchDoubleY()
Get the y coordinate of the origin of the sketch, in double precision. The origin is the point on the sketch where the turtle started out.

Returns:
the y coordinate of the origin of the sketch, in double precision

getSketchLocation

public Location getSketchLocation()
Get the location of the origin of the sketch. The origin is the point on the sketch where the turtle started out.

Returns:
the origin of the sketch in a Location object

getSketchRotation

public double getSketchRotation()
Get the angle of rotation of this turtle's sketch

Returns:
the angle of rotation

getSketchScale

public double getSketchScale()
Get the scale factor of the sketch - the degree to which it has been shrunk or expanded. A factor of 2 means it is twice as big as it was drawn; .25 means it is a quarter of the size it was drawn at; 1 means it is exactly the size it started, and so on.

Returns:
the scale factor

getSketchX

public int getSketchX()
Get the x coordinate of the origin of the sketch, in int precision. The origin is the point on the sketch where the turtle started out.

Returns:
the x coordinate of the origin of the sketch, in int precision

getSketchY

public int getSketchY()
Get the y coordinate of the origin of the sketch, in int precision. The origin is the point on the sketch where the turtle started out.

Returns:
the y coordinate of the origin of the sketch, in int precision

getStroke

public BasicStroke getStroke()
Return the stroke used for this object's lines.

Specified by:
getStroke in interface DrawableStrokeInterface
Returns:
the stroke used for this object's lines

getX

public int getX()
Get this object's x coordinate.

Specified by:
getX in interface LocatableInterface
Returns:
this object's x coordinate

getY

public int getY()
Get this object's y coordinate.

Specified by:
getY in interface LocatableInterface
Returns:
this object's y coordinate

hide

public void hide()
Make this object invisible. It stays in position on its canvas; it is simply not drawn. This method has no effect if the object was already hidden.

Specified by:
hide in interface DrawableInterface
Overrides:
hide in class objectdraw.ObjectDrawShape

hideTurtle

public void hideTurtle()
A little triangle-shaped icon represents the turtle while it is drawing the sketch, to make it easier for you to see where the turtle is and which way it is facing when you are trying to figure out how to get it to draw a shape. You can hide that icon and leave just the sketch visible by using this method.


isHidden

public boolean isHidden()
Return true if this object has been rendered invisible with a call to its hide() method, false if it is still being drawn.

Specified by:
isHidden in interface DrawableInterface
Overrides:
isHidden in class objectdraw.ObjectDrawShape
Returns:
whether this object is hidden

isPenDown

public boolean isPenDown()
Determine whether the turtle is leaving a line behind as it moves

Returns:
whether the turtle is leaving a line behind as it moves

isTurtleHidden

public boolean isTurtleHidden()
Determine whether the turtle's icon is hidden

Returns:
whether the turtle's icon is hidden

lt

public void lt()
Turn 90° to the left.


lt

public void lt(double angle)
Turn angle degrees to the left

Parameters:
angle - number of degrees to turn

move

public void move()
Move forward 40 pixels


move

public void move(double distance)
Move forward distance pixels

Parameters:
distance - number of pixels to move

move

public void move(double dx,
                 double dy)
Shift (translate) this object left or right by an amount dx, and up or down by an amount dy. A negative dx indicates a shift to the left; a negative dy indicates a shift up

Specified by:
move in interface DrawableInterface
Overrides:
move in class objectdraw.ObjectDrawShape
Parameters:
dx - amount of x translation
dy - amount of y translation

moveSketch

public void moveSketch(double dx,
                       double dy)
Move the turtle and its entire sketch by the given amount in the x and y.

Parameters:
dx - distance to shift the sketch in the x direction
dy - distance to shift the sketch in the y direction

moveSketchTo

public void moveSketchTo(double x,
                         double y)
Move the origin on the sketch to (x, y). The origin is the point on the sketch where the turtle started out.

Parameters:
x - x coordinate to move the origin to
y - y coordinate to move the origin to

moveSketchTo

public void moveSketchTo(Location point)
Move the origin on the sketch to the given Location. The origin is the point on the sketch where the turtle started out.

Parameters:
point - Location to move the origin to

moveTo

public void moveTo(double x,
                   double y)
Move the reference point of this object to the given location. For a Drawable2D object, the reference point is the top left corner; for a line, it is the start point.

Specified by:
moveTo in interface DrawableInterface
Overrides:
moveTo in class objectdraw.ObjectDrawShape
Parameters:
x - x coordinate to move to
y - y coordinate to move to

moveTo

public void moveTo(Location point)
Move the reference point of this object to the given location. For a Drawable2D object, the reference point is the top left corner; for a line, it is the start point.

Specified by:
moveTo in interface DrawableInterface
Overrides:
moveTo in class objectdraw.ObjectDrawShape
Parameters:
point - Location to move to

penDown

public void penDown()
Tell the turtle to resume drawing a line behind it as it moves.


penUp

public void penUp()
Tell the turtle to lift up its pen, so that it moves without drawing a line behind it. It can still outline fill areas with its movements.


recolorSketch

public void recolorSketch(Color original,
                          Color substitute)
Replace all parts of the sketch that were drawn in the color original with the new color substitute.

Parameters:
original - Color with which a portion of the sketch was originally drawn
substitute - Color to replace that portion of the sketch with

removeFromCanvas

public void removeFromCanvas()
Remove this object from its canvas.

Specified by:
removeFromCanvas in interface DrawableInterface
Overrides:
removeFromCanvas in class objectdraw.ObjectDrawShape

rotateSketch

public void rotateSketch(double byAngle)
Rotate this sketch by the given angle, in degrees. This adds on to any previous rotation.

Parameters:
byAngle - angle to rotate by. Positive rotates left, negative rotates right.

rt

public void rt()
Turn 90° to the right.


rt

public void rt(double angle)
Turn angle degrees to the right

Parameters:
angle - number of degrees to turn

scaleSketch

public void scaleSketch(double byFactor)
Add a scale factor to this turtle's sketch, causing it to be shrunk or expanded. A scale factor of .5 shrinks it to half size, a factor of 3 makes it three times bigger, and so on. The scaling is centered around the starting point of the turtle. This effect adds on to whatever scaling you have already done.

Parameters:
byFactor - factor by which the sketch should be scaled

sendBackward

public void sendBackward()
Move this object one step backward in the draw order, causing it to be drawn underneath the objects that are in front of it.

Specified by:
sendBackward in interface DrawableInterface
Overrides:
sendBackward in class objectdraw.ObjectDrawShape

sendForward

public void sendForward()
Move this object one step forward in the draw order, causing it to be drawn on top of the objects that are behind it.

Specified by:
sendForward in interface DrawableInterface
Overrides:
sendForward in class objectdraw.ObjectDrawShape

sendToBack

public void sendToBack()
Move this object to the very back of the draw order, causing it to be drawn underneath all the other objects.

Specified by:
sendToBack in interface DrawableInterface
Overrides:
sendToBack in class objectdraw.ObjectDrawShape

sendToFront

public void sendToFront()
Move this object to the very front of the draw order, causing it to be drawn on top of all the other objects.

Specified by:
sendToFront in interface DrawableInterface
Overrides:
sendToFront in class objectdraw.ObjectDrawShape

setColor

public void setColor(Color c)
Change the color of this object.

Specified by:
setColor in interface DrawableInterface
Overrides:
setColor in class objectdraw.ObjectDrawShape
Parameters:
c - new Color for this object

setHeading

public void setHeading(double heading)
Give the turtle a new heading

Parameters:
heading - the degree angle toward which you want the turtle to face

setLineWidth

public void setLineWidth(double width)
Set the width of this object's lines

Specified by:
setLineWidth in interface DrawableStrokeInterface
Parameters:
width - the new width of this object's lines

setSketchRotation

public void setSketchRotation(double angle)
Set the angle, in degrees, by which this sketch should be rotated. Rotation occurs centered around the starting point of the turtle.

Parameters:
angle - angle of rotation of the sketch

setSketchScale

public void setSketchScale(double factor)
Set the scale factor of this turtle's sketch, causing it to be shrunk or expanded. A scale factor of 1 dispalys the sketch at true size, a factor of .5 displays it at half size, a factor of 3 makes it three times bigger, and so on. The scaling is centered around the starting point of the turtle.

Parameters:
factor - factor to which the sketch should be scaled

setStroke

public void setStroke(BasicStroke stroke)
Set the stroke used for this object's lines

Specified by:
setStroke in interface DrawableStrokeInterface
Parameters:
stroke - the new stroke for this object's lines

show

public void show()
Make an object visible again after it had been hidden. This method has no effect if the object was already visible.

Specified by:
show in interface DrawableInterface
Overrides:
show in class objectdraw.ObjectDrawShape

showTurtle

public void showTurtle()
Show the turtle icon again after it had been hidden


toString

public String toString()
Return a string describing how this object might be constructed.

Overrides:
toString in class objectdraw.ObjectDrawObject