ch.aplu.gidlet
Class Turtle

java.lang.Object
  ch.aplu.gidlet.Turtle

public class Turtle
extends java.lang.Object

Logo-like turtle that moves on a graphics display, called playground. The coordinate system has it's reference point in the middle of the screen with x-coordinates to the right and y-coordinates upward both in the range -200..200 (doubles). For simplicity the turtle shape is a triangle. Each turtle instance has it's own playground. The most recent turtle's playground is visible, while other playgrounds or Gui windows become hidden. The hidden windows may be updated in any way, but the change is only visible, when calling their show() method.
Default colors:
background (playground) color: black
turtle color: light gray
turtle pen color: white
fill color: white

Example:

import ch.aplu.gidlet.*;

public class TurtleGidlet extends Gidlet
{
  public void main()
  {
    Turtle t = new Turtle();

    for (int i = 0; i < 18; i++)
    {
      for (int k = 0; k < 4; k++)
        t.forward(100).left(90);
      t.left(20);
    }
  }
}
 

Nested Class Summary

protected class

Turtle.PointD

Field Summary

protected ch.aplu.gidlet.TurtleShape

shape

Constructor Summary

Turtle()
Constructs a Turtle instance with default background (playground) color and default turtle color.

Turtle(boolean visible)
Constructs a Turtle instance with given visibility, default background (playground) color and default turtle color.

Turtle(int color)
Constructs a Turtle instance with default background (playground) color and given turtle color.

Turtle(int color, boolean visible)
Constructs a Turtle instance with default background (playground) color, given turtle color and visibility.

Turtle(int bgColor, int color, boolean visible)
Constructs a Turtle instance with given background (playground) color, turtle color and visibility.

Turtle(java.lang.String title)
Constructs a Turtle instance with given playground title, default background (playground) color and default turtle color.

Turtle(java.lang.String title, int bgColor, int color, boolean visible)
Constructs a Turtle instance with given playground title, background (playground) color, turtle color and visibility.

Turtle(java.lang.String title, int bgColor, int color, boolean visible, boolean showPlayground)
Constructs a Turtle instance with given playground title, background (playground) color, turtle color and visibility.

Turtle(Turtle t)
Creates a turtle clone that has exactly the same properties, playground title and traces as the given turtle.

Turtle(Turtle t, java.lang.String title)
Creates a turtle clone that has exactly the same properties and traces as the given turtle, but the playground has the given title.

Method Summary

double	_getX() Returns the x-coordinate.
double	_getY() Returns the y-coordinate.
Turtle	addKeyListener(KeyListener keyListener) Registers an KeyListener to get a notification when a button is clicked.
Turtle	back(double s) Moves turtle the given distance backward.
Turtle	beep() Emits a beep.
Turtle	bk(double s) Short for back().
Turtle	clean() Erases traces and text, but let turtle where it is.
Turtle	clear() Clears the entire playground.
Turtle	clip() Causes turtle not to wrap around playground borders, e.g. when it leaves the playground it disappaers.
Turtle	clone() Creates a new turtle that has exactly the same properties, playground title and traces.
Turtle	clone(java.lang.String title) Creates a new turtle that has exactly the same properties and traces, but the given playground title.
double	distance(double x, double y) Returns the distance from the current position to the given position.
Turtle	drawLabel(int index, java.lang.String text) Draws the given text using the current pen color and text font at the current turtle position.
boolean	enableRepaint(boolean b) Enables/disables automatic updating the window after each turtle movement.
Turtle	eraseLabel(int index) Erases the text with given index.
Turtle	fd(double s) Short for forward().
Turtle	fillOff() Stops the filling started by calling fillToPoint(), fillToHorizontal() or fillToVertical().
Turtle	fillToHorizontal(double y) Draws a imaginary horizonatal line at given y-coordinate, when the turtle subsequently moves around, the trapezoidal area that is covered by this line and the turtle position is filled using the current fill color.
Turtle	fillToPoint(double x, double y) Attachs a imaginary rubber band at the given position, when the turtle subsequently moves around, the area that is covered by the rubber band is filled using the current fill color.
Turtle	fillToVertical(double x) Draws a imaginary vertical line at given x-coordinate, when the turtle subsequently moves around, the trapezoidal area that is covered by this line and the turtle position is filled using the current fill color.
Turtle	forward(double s) Moves turtle the given distance forward.
int	getColor() Returns the turtle color.
Playground	getPlayground() Returns the turtle's playground, which is an instance of javax.microedition.lcdui.Canvas.
double	getX() Returns the x-coordinate.
double	getY() Returns the y-coordinate.
double	heading() Returns the angle of vision (angle in respect to north, positive clockwise).
Turtle	hideTurtle() Makes turtle invisible.
Turtle	home() Moves the turtle to the initial position at (0, 0) looking north.
Turtle	ht() Short for hideTurtle().
protected void	init() Initializes Turtle.
boolean	isHidden() Returns true if turtle is invisible (hidden), otherwise false.
boolean	isPenUp() Returns true if turtle's pen is up, otherwise false.
boolean	isWrap() Returns true, if turtle is in wrap mode, otherwise false.
Turtle	left(double angle) Turns turtle the given angle (in degrees) to the left.
Turtle	lt(double angle) Short for left().
Turtle	pd() Short for penDown().
Turtle	pe() Short for penErase().
Turtle	penDown() Lower pen, so that the trace is drawn.
Turtle	penErase() Changes pen color to the background color.
Turtle	penUp() Lifts pen, so that the trace is not drawn.
Turtle	pu() Short for penUp().
Turtle	removeKeyListener() Removes a registered KeyListener.
Turtle	repaint() Performs manual repainting when automatic repainting is disabled.
Turtle	right(double angle) Turns turtle the given angle (in degrees) to the right.
Turtle	rt(double angle) Short for right().
Turtle	setColor(int color) Sets turtle's color to the given color.
Turtle	setColor(int r, int g, int b) Sets turtle's color to the given color in RGB-format.
Turtle	setDelay(int time) Sets the given time delay in ms after each turtle movement.
Turtle	setFillColor(int color) Sets the color for subsequent filling.
Turtle	setFillColor(int r, int g, int b) Sets the color in RGB-format for subsequent filling.
Turtle	setFont(int face, int style, int size) Sets the current text font for drawing labels.
Turtle	setH(double angle) Short for setHeading().
Turtle	setHeading(double angle) Sets the angle of vision (angle in respect to north, positive clockwise) to the given value (in degrees).
Turtle	setPenColor(int color) Sets turtle's pen color to the given color.
Turtle	setPenColor(int r, int g, int b) Sets turtle's pen color to the given color in RGB-format.
Turtle	setPos(double x, double y) Sets turtle to the given coordinates, without drawing a trace.
Turtle	setPosX(double x) Sets turtle to the given x-position without drawing a trace while the y-coordinate remains unchanged.
Turtle	setPosY(double y) Sets turtle to the given y-position, without drawing a trace while the x-coordinate remains unchanged.
Turtle	setX(double x) Sets turtle to the given x-position, while the y-coordinate remains the same; if pen is down, a trace from the last to the given position is drawn.
Turtle	setXY(double x, double y) Sets turtle to the given coordinates; if pen is down, a trace from the last to the given position is drawn.
Turtle	setY(double y) Sets turtle to the given y-position, while the x-coordinate remains the same; if pen is down, a trace from the last to the given position is drawn.
Turtle	showPlayground() Shows the playground if it's hidden by another window.
Turtle	showTurtle() Makes turtle visible.
Turtle	st() Short for showTurtle().
Turtle	stampTurtle() Draws a turtle shape of same color at the current position.
int	toPixelX(double x) Converts from turtle x-coordinates to pixel x-coordinates.
int	toPixelY(double y) Converts from turtle y-coordinates to pixel y-coordinates.
double	toTurtleX(int x) Converts from pixel x-coordinates to turtle x-coordinates.
double	toTurtleY(int y) Converts from pixel y-coordinates to turtle y-coordinates.
double	towards(double x, double y) Returns the direction from the current to the given position in degrees (-180..180).
java.lang.String	version() Returns version information.
Turtle	wrap() Causes turtle to wrap around playground borders, e.g. when it leaves the playground on one border, it reappears on the opposite border.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

shape

protected ch.aplu.gidlet.TurtleShape shape

Constructor Detail

Turtle

public Turtle(Turtle t,
              java.lang.String title)

Creates a turtle clone that has exactly the same properties and traces as the given turtle, but the playground has the given title. Its playground is initially hidden and becomes the current window by calling showPlayground().

See Also:

clone(java.lang.String), showPlayground()

Turtle

public Turtle(Turtle t)

Creates a turtle clone that has exactly the same properties, playground title and traces as the given turtle. Its playground is initially hidden and becomes the current window by calling showPlayground().

See Also:

clone(java.lang.String), showPlayground()

Turtle

public Turtle(java.lang.String title,
              int bgColor,
              int color,
              boolean visible,
              boolean showPlayground)

Constructs a Turtle instance with given playground title, background (playground) color, turtle color and visibility.
If showPlayground = false, the turtle's window is initially invisible and must made visible by calling showPlayground(). Turtle is at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(java.lang.String title,
              int bgColor,
              int color,
              boolean visible)

Constructs a Turtle instance with given playground title, background (playground) color, turtle color and visibility.
Turtle is at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(int bgColor,
              int color,
              boolean visible)

Constructs a Turtle instance with given background (playground) color, turtle color and visibility.
Turtle is at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(int color,
              boolean visible)

Constructs a Turtle instance with default background (playground) color, given turtle color and visibility.
Turtle is at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(int color)

Constructs a Turtle instance with default background (playground) color and given turtle color.
Turtle is visible at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(boolean visible)

Constructs a Turtle instance with given visibility, default background (playground) color and default turtle color.
Turtle is at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle(java.lang.String title)

Constructs a Turtle instance with given playground title, default background (playground) color and default turtle color.
Turtle is visible at position (0,0) looking north. Wrapping is off and pen is down.

Turtle

public Turtle()

Constructs a Turtle instance with default background (playground) color and default turtle color.
Turtle is visible at position (0,0) looking north. Wrapping is off and pen is down.

Method Detail

init

protected void init()

Initializes Turtle. Called by main() if Turtle is created before main() is called.

forward

public Turtle forward(double s)

Moves turtle the given distance forward. Returns the Turtle reference.

fd

public Turtle fd(double s)

Short for forward().

See Also:

forward(double)

back

public Turtle back(double s)

Moves turtle the given distance backward. Returns the Turtle reference.

bk

public Turtle bk(double s)

Short for back().

See Also:

back(double)

right

public Turtle right(double angle)

Turns turtle the given angle (in degrees) to the right. Returns the Turtle reference.

rt

public Turtle rt(double angle)

Short for right().

See Also:

right(double)

left

public Turtle left(double angle)

Turns turtle the given angle (in degrees) to the left. Returns the Turtle reference.

lt

public Turtle lt(double angle)

Short for left().

See Also:

left(double)

getX

public double getX()

Returns the x-coordinate. If wrapping is on, return the wrapped coordinate within the playground range.

getY

public double getY()

Returns the y-coordinate. If wrapping is on, return the wrapped coordinate within the playground range.

_getX

public double _getX()

Returns the x-coordinate. Even if wrapping is on, return the unwrapped coordinate not bound to the playground range.

_getY

public double _getY()

Returns the y-coordinate. If wrapping is on, return the unwrapped coordinate not bound the playground range.

getColor

public int getColor()

Returns the turtle color.

beep

public Turtle beep()

Emits a beep. Returns the Turtle reference.

clean

public Turtle clean()

Erases traces and text, but let turtle where it is. Stamped turtles are erased. If the turtle is hidden, it remains hidden. Returns the Turtle reference.

clear

public Turtle clear()

Clears the entire playground. Reset all turtle properties to starting values. Returns the Turtle reference.

distance

public double distance(double x,
                       double y)

Returns the distance from the current position to the given position.

heading

public double heading()

Returns the angle of vision (angle in respect to north, positive clockwise).

hideTurtle

public Turtle hideTurtle()

Makes turtle invisible. Returns the Turtle reference.

ht

public Turtle ht()

Short for hideTurtle().

See Also:

hideTurtle()

isHidden

public boolean isHidden()

Returns true if turtle is invisible (hidden), otherwise false.

isPenUp

public boolean isPenUp()

Returns true if turtle's pen is up, otherwise false.

penDown

public Turtle penDown()

Lower pen, so that the trace is drawn. Returns the Turtle reference.

pd

public Turtle pd()

Short for penDown().

See Also:

penDown()

penUp

public Turtle penUp()

Lifts pen, so that the trace is not drawn. Returns the Turtle reference.

pu

public Turtle pu()

Short for penUp().

See Also:

penUp()

setColor

public Turtle setColor(int color)

Sets turtle's color to the given color. Returns the Turtle reference.

setColor

public Turtle setColor(int r,
                       int g,
                       int b)

Sets turtle's color to the given color in RGB-format. Returns the Turtle reference.

setPenColor

public Turtle setPenColor(int color)

Sets turtle's pen color to the given color. Returns the Turtle reference.

setPenColor

public Turtle setPenColor(int r,
                          int g,
                          int b)

Sets turtle's pen color to the given color in RGB-format. Returns the Turtle reference.

penErase

public Turtle penErase()

Changes pen color to the background color. Returns the Turtle reference.

pe

public Turtle pe()

Short for penErase().

See Also:

penErase()

setHeading

public Turtle setHeading(double angle)

Sets the angle of vision (angle in respect to north, positive clockwise) to the given value (in degrees). Returns the Turtle reference.

setH

public Turtle setH(double angle)

Short for setHeading().

See Also:

setHeading(double)

setXY

public Turtle setXY(double x,
                    double y)

Sets turtle to the given coordinates; if pen is down, a trace from the last to the given position is drawn. The angle of vision is not changed. Returns the Turtle reference.

setX

public Turtle setX(double x)

Sets turtle to the given x-position, while the y-coordinate remains the same; if pen is down, a trace from the last to the given position is drawn. The angle of vision is not changed. Returns the Turtle reference.

setY

public Turtle setY(double y)

Sets turtle to the given y-position, while the x-coordinate remains the same; if pen is down, a trace from the last to the given position is drawn. The angle of vision is not changed. Returns the Turtle reference.

setPos

public Turtle setPos(double x,
                     double y)

Sets turtle to the given coordinates, without drawing a trace. The angle of vision is not changed. Returns the Turtle reference.

setPosX

public Turtle setPosX(double x)

Sets turtle to the given x-position without drawing a trace while the y-coordinate remains unchanged. The angle of vision is not changed. Returns the Turtle reference.

setPosY

public Turtle setPosY(double y)

Sets turtle to the given y-position, without drawing a trace while the x-coordinate remains unchanged. The angle of vision is not changed. Returns the Turtle reference.

showTurtle

public Turtle showTurtle()

Makes turtle visible. Returns the Turtle reference.

st

public Turtle st()

Short for showTurtle().

See Also:

showTurtle()

toTurtleX

public double toTurtleX(int x)

Converts from pixel x-coordinates to turtle x-coordinates.

toTurtleY

public double toTurtleY(int y)

Converts from pixel y-coordinates to turtle y-coordinates.

toPixelX

public int toPixelX(double x)

Converts from turtle x-coordinates to pixel x-coordinates.

toPixelY

public int toPixelY(double y)

Converts from turtle y-coordinates to pixel y-coordinates.

version

public java.lang.String version()

Returns version information.

wrap

public Turtle wrap()

Causes turtle to wrap around playground borders, e.g. when it leaves the playground on one border, it reappears on the opposite border. The turlte should not move further than to adjacent playgrounds in one single operation. Returns the Turtle reference.

isWrap

public boolean isWrap()

Returns true, if turtle is in wrap mode, otherwise false.

See Also:

wrap()

clip

public Turtle clip()

Causes turtle not to wrap around playground borders, e.g. when it leaves the playground it disappaers. Returns the Turtle reference.

See Also:

wrap()

drawLabel

public Turtle drawLabel(int index,
                        java.lang.String text)

Draws the given text using the current pen color and text font at the current turtle position. The given index is used to reference the text for erasing. If the label is already in use, the previous text is overwritten. Returns the Turtle reference.

See Also:

eraseLabel(int)

eraseLabel

public Turtle eraseLabel(int index)

Erases the text with given index. If text with given index does not exist, nothing happens. Returns the Turtle reference.

See Also:

drawLabel(int, java.lang.String)

setFont

public Turtle setFont(int face,
                      int style,
                      int size)

Sets the current text font for drawing labels. If the font is changed, also existing labels are affected. Returns the Turtle reference. Default font is FACE_SYSTEM, STYLE_PLAIN, SIZE_MEDIUM)

Parameters:

face - one of Font.FACE_SYSTEM, Font.FACE_MONOSPACE, or Font.FACE_PROPORTIONAL

style - Font.STYLE_PLAIN, or a combination of Font.STYLE_BOLD, Font.STYLE_ITALIC, and Font.STYLE_UNDERLINED

size - one of Font.SIZE_SMALL, Font.SIZE_MEDIUM, or Font.SIZE_LARGE

See Also:

drawLabel(int, java.lang.String)

addKeyListener

public Turtle addKeyListener(KeyListener keyListener)

Registers an KeyListener to get a notification when a button is clicked. Returns the Turtle reference.

removeKeyListener

public Turtle removeKeyListener()

Removes a registered KeyListener. Returns the Turtle reference.

setDelay

public Turtle setDelay(int time)

Sets the given time delay in ms after each turtle movement. Returns the Turtle reference.

towards

public double towards(double x,
                      double y)

Returns the direction from the current to the given position in degrees (-180..180). Angle from north, positive clockwise.

home

public Turtle home()

Moves the turtle to the initial position at (0, 0) looking north. Other properties and the traces are not changed. Returns the Turtle reference.

enableRepaint

public boolean enableRepaint(boolean b)

Enables/disables automatic updating the window after each turtle movement. If disabled, call repaint() to perform manual repainting. Disabling speeds up program execution enormously. Returns true, if repainting is currently enabled, otherwise false.

See Also:

repaint()

repaint

public Turtle repaint()

Performs manual repainting when automatic repainting is disabled. Returns the Turtle reference.

See Also:

enableRepaint(boolean)

setFillColor

public Turtle setFillColor(int color)

Sets the color for subsequent filling. Returns the Turtle reference.

See Also:

fillToPoint(double, double), fillToHorizontal(double), fillToVertical(double)

setFillColor

public Turtle setFillColor(int r,
                           int g,
                           int b)

Sets the color in RGB-format for subsequent filling. Returns the Turtle reference.

See Also:

fillToPoint(double, double), fillToHorizontal(double), fillToVertical(double)

fillToPoint

public Turtle fillToPoint(double x,
                          double y)

Attachs a imaginary rubber band at the given position, when the turtle subsequently moves around, the area that is covered by the rubber band is filled using the current fill color. Filling is on until fillOff() is called. Returns the Turtle reference.

fillToHorizontal

public Turtle fillToHorizontal(double y)

Draws a imaginary horizonatal line at given y-coordinate, when the turtle subsequently moves around, the trapezoidal area that is covered by this line and the turtle position is filled using the current fill color. Filling is on until fillOff() is called. Returns the Turtle reference.

fillToVertical

public Turtle fillToVertical(double x)

Draws a imaginary vertical line at given x-coordinate, when the turtle subsequently moves around, the trapezoidal area that is covered by this line and the turtle position is filled using the current fill color. Filling is on until fillOff() is called. Returns the Turtle reference.

fillOff

public Turtle fillOff()

Stops the filling started by calling fillToPoint(), fillToHorizontal() or fillToVertical(). Returns the Turtle reference.

See Also:

fillToPoint(double, double), fillToHorizontal(double), fillToVertical(double)

showPlayground

public Turtle showPlayground()

Shows the playground if it's hidden by another window. The turtle's playground may be hidden, because another turtle's playground or some other Gui window became the current window.

clone

public Turtle clone(java.lang.String title)

Creates a new turtle that has exactly the same properties and traces, but the given playground title. Its playground is initially hidden and becomes the current window by calling showPlayground. The given title is the title of the new playground. Returns the reference to the new turtle.

clone

public Turtle clone()

Creates a new turtle that has exactly the same properties, playground title and traces. Its playground is initially hidden and becomes the current window by calling showPlayground. Returns the reference to the new turtle.

stampTurtle

public Turtle stampTurtle()

Draws a turtle shape of same color at the current position. This shape will remain at this position when the turtle moves away. Returns the Turtle reference.

getPlayground

public Playground getPlayground()

Returns the turtle's playground, which is an instance of javax.microedition.lcdui.Canvas. Useful for low level operations, e.g. checking key events with getPlayground().getGameAction(keyCode).