Turtle Graphics with Java

Bern University of Teacher Education  
HomeStart Online-EditorPrintAndroid-TurtlegraphicsJava-Online
Turtle
ch.aplu.turtle

Class Turtle

  • All Implemented Interfaces:
    java.lang.Cloneable


    public class Turtle
    extends java.lang.Object
    implements java.lang.Cloneable
    The core class for turtles. Default turtle coordinate system: doubles -200.0..+200.0 in both directions (zero at center; x to left, y upward). Turtle coordinates are rounded to to 400 x 400 pixel coordinates.
    Unless special constructors are used, new turtles are shown in a new window.
    Defaults when a turtle is created:
    Coordinates: (0, 0) (center of window)
    Heading: north
    Speed: 200 (coordinates per seconds)

    Default properties of the turtle and it's playground can be changed from the library defaults by using a Java properties file turtlegraphics.properties. For more details consult turtlegraphics.properties file found in the distribution.

    When the close button of the console window title bar is hit, System.exit(0) is executed that terminates the JVM, but you can modifiy this behavior by using the key ConsoleClosingMode in turtlegraphics.properties. If the value RELEASE_ON_CLOSE is selected, every public Turtle drawing method checks if the frame is closed and throws a RuntimeException if this is the case.

     ================ UML diagram ===========================================
     -----------              --------------------------       ------------
     |JPanel     |            |interface                 |     |JFrame      |
     |-----------|            |TurtleContainer           |     |----------- |
     |           |            |--------------------------|     |            |
     |           |            |Playground getPlayground()|     |            |
     -----------              --------------------------       ------------
     ^                               ^                           ^
     | is-a                          |                           |
     |                               |                           |
     -----------                     |                           |
     |class      |                   |                           | is-a
     |Playground |                   |implements                 |
     |-----------|                   |                           |
     |           |                   |                           |
     |           |                   |              -------------
     -----------                     |             |
     ^ o                   --------------------------------
     | |                  |class                           |
     | |     has-a        |TurtleFrame                     |
     | |    (creates)     |------------------------------- |
     |  ----------------- |TurtleFrame(...new Playground())|
     | is-a               |Playground playground           |
     |                     --------------------------------
     ----------                            o
     |class     |                          | has-a (creates)
     |TurtlePane|                          |
     |----------|                          |
     |          |             --------------------------------
     |          |            |class                           |
     ----------             |Turtle                          |
     |------------------------------- |
     |TurtleFrame turtleFrame         |
     |                                |
     --------------------------------
    
     ========================================================================
     
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int APPLETFRAME
      Mode attribute for turtle applets in a standalone window (value: 1).
      static int ASK_ON_CLOSE
      Mode attribute for a turtle frame that opens a confirm dialog when the close button is hit (value: 3).
      static java.awt.Color BLACK 
      static java.awt.Color BLUE
      Short for Color.BLUE.
      static int CLEAR_ON_CLOSE
      Mode attribute for a turtle frame that calls Turtle.clear() when the close button is hit (value: 2).
      static java.awt.Color CYAN
      Short for Color.CYAN.
      static int DISPOSE_ON_CLOSE
      Mode attribute for a turtle frame that closes the turtle frame and releases grapics resources (value: 4), but does not call System.exit().
      static java.awt.Color DKGRAY
      Short for Color.GRAY.
      static java.awt.Color GRAY
      Short for Color.GRAY.
      static java.awt.Color GREEN
      Short for Color.GREEN.
      static java.awt.Color LTGRAY
      Short for Color.LIGHT_GRAY.
      static java.awt.Color MAGENTA
      Short for Color.MAGENTA.
      static int NOTHING_ON_CLOSE
      Mode attribute for a turtle frame that does nothing when the close button is hit (value: -1).
      static java.awt.Color RED
      Short for Color.RED.
      static int RELEASE_ON_CLOSE
      Mode attribute for a turtle frame that closes the turtle frame by disposing all resources (value: 5), but does not call System.exit().
      static int STANDARDFRAME
      Mode attribute for normal turtle applications (default, value: 0).
      static java.awt.Color WHITE
      Short for Color.WHITE.
      static java.awt.Color YELLOW
      Short for Color.YELLOW.
    • Constructor Summary

      Constructors 
      Constructor and Description
      Turtle()
      Creates a new turtle in its own new window.
      Turtle(boolean show)
      Creates a new turtle with specified visibility in its own new window.
      Turtle(java.awt.Color color)
      Creates a new turtle with specified color in its own new window.
      Turtle(javax.swing.JMenuBar menuBar, java.awt.Color color)
      Creates a new turtle with specified color in its own new window with the given menu.
      Turtle(java.lang.String colorStr)
      Creates a new turtle with specified color as string in its own new window.
      Turtle(Turtle otherTurtle)
      Creates a new turtle in the same TurtleContainer (window) as the given turtle.
      Turtle(Turtle otherTurtle, boolean show)
      Creates a new turtle in the same TurtleContainer (window) as the given turtle and specifies its visibility.
      Turtle(Turtle otherTurtle, java.awt.Color color)
      Creates a new turtle with the specified color in the same TurtleContainer (window) as the given turtle.
      Turtle(TurtleContainer turtleContainer)
      Creates a new turtle in the given TurtleContainer.
      Turtle(TurtleContainer turtleContainer, boolean show)
      Creates a new turtle with specified visibility in the given TurtleContainer.
      Turtle(TurtleContainer turtleContainer, java.awt.Color color)
      Creates a new turtle with specified color in the given TurtleContainer.
      Turtle(TurtleContainer turtleContainer, java.lang.String colorStr)
      Creates a new turtle with specified color as a string in the given TurtleContainer.
      Turtle(TurtlePane turtlePane)
      Creates a new turtle in the given TurtlePane.
      Turtle(Turtle otherTurtle, java.lang.String colorStr)
      Creates a new turtle with specified color as string in the same TurtleContainer (window) as the given turtle.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      java.awt.geom.Point2D.Double _getPos()
      Returns the current unbounded turtle position.
      double _getX()
      Returns the current unbounded turtle's x-coordinate.
      double _getY()
      Returns the current unbounded turtle's y-coordinate.
      void _sleep(int time)
      Non-static version of sleep().
      void addComponentListener(java.awt.event.ComponentListener listener)
      Adds the specified component listener to receive component events.
      void addFocusListener(java.awt.event.FocusListener listener)
      Adds the specified focus listener to receive focus events.
      void addKeyListener(java.awt.event.KeyListener listener)
      Adds the specified key listener to receive key events.
      void addMouseHitListener(MouseHitListener listener)
      Adds the specified mouse-hit listener to receive mouse events.
      void addMouseHitXListener(MouseHitXListener listener)
      Adds the specified mouse-hit-x listener to receive mouse events.
      void addMouseListener(java.awt.event.MouseListener listener)
      Adds the specified mouse listener to receive mouse events.
      void addMouseMotionListener(java.awt.event.MouseMotionListener listener)
      Adds the specified mouse motion listener to receive mouse motion events.
      void addStatusBar(int height)
      Adds a status window attached at the bottom of the game grid window.
      void addWindowFocusListener(java.awt.event.WindowFocusListener listener)
      Adds the specified window focus listener to receive window focus events.
      void addWindowListener(java.awt.event.WindowListener listener)
      Adds the specified window listener to receive window events.
      Turtle antiAliasing(boolean on)
      Sets anti-aliasing (for the turtle trace buffer) on or off.
      Turtle back(double distance)
      Same as bk().
      Turtle beep()
      Emits a 'beep'.
      Turtle bk(double distance)
      Moves the turtle backwards.
      Turtle clean()
      Clears the turtle's playground.
      Turtle clean(java.awt.Color color)
      Clears the turtle's playground but painting it with the given color.
      Turtle clean(java.lang.String colorStr)
      Clears the turtle's playground but painting it with the given color.
      Turtle clear()
      Clears the turtle's playground.
      Turtle clear(java.awt.Color color)
      Clears the turtle's playground but painting it with the given color.
      Turtle clear(java.lang.String colorStr)
      Clears the turtle's playground but painting it with the given color.
      Turtle clearStates()
      Empties the state buffer.
      Turtle clip()
      Sets the turtle to clip mode.
      java.lang.Object clone()
      Creates a partial clone of the turtle.
      void dispose()
      Disposes the TurtleFrame.
      double distance(double x, double y)
      Returns the distance between the current turtle position and the given position,
      double distance(java.awt.geom.Point2D.Double pt)
      Returns the distance between the current turtle position and the given position,
      Turtle dot(double radius)
      Draws a dot (filled circle) at the current turtle position using the current pen color.
      void enableRepaint(boolean b)
      Enables/disables automatic repainting (default: enabled).
      Turtle fd(double distance)
      Moves the turtle forwards.
      Turtle fill()
      Fills a closed region (flood fill) with the current fill color (default: Color.blue).
      Turtle fill(double x, double y)
      /** Fills a closed region (flood fill) with the current fill color (default: Color.blue) as if the turtle where at the given coordinates.
      Turtle fillOff()
      Stops the filling started by calling fillToPoint(), fillToHorizontal() or fillToVertical().
      Turtle fillPath()
      Closes the path (line from current position to where the turtle path starts) and fills the polygon with the current fill color.
      Turtle fillToHorizontal(double y)
      Draws a imaginary horizonatal line at given y-coordinate.
      Turtle fillToPoint()
      Same as fillToPoint(x, y) using the current turtle coordinates.
      Turtle fillToPoint(double x, double y)
      Attachs a imaginary rubber band between the turtle and the given anchor point.
      Turtle fillToVertical(double x)
      Draws a imaginary vertical line at given x-coordinate.
      Turtle forward(double distance)
      Same as fd().
      static java.lang.String[] getAvailableFontFamilies()
      Provides information about all font families currently available on your system.
      java.awt.Color getColor()
      Returns the turtle's current color.
      java.lang.String getColorStr()
      Returns the X11 color string of the turtle's current color.
      static java.lang.String getEnvironment()
      Returns environment information (JRE and OS).
      java.awt.Color getFillColor()
      Returns the turtle's current fill color.
      java.lang.String getFillColorStr()
      Returns the X11 color string of the turtle's current fill color.
      java.awt.Font getFont()
      Returns the current font.
      TurtleFrame getFrame()
      Returns the turtle's TurtleFrame (derivated from JFrame).
      Pen getPen()
      Return the turtle's Pen reference.
      java.awt.Color getPenColor()
      Returns the turtle's pen color.
      java.lang.String getPenColorStr()
      Returns the X11 color string of the turtle's current pen color.
      java.awt.Color getPixelColor()
      Returns the color of the pixel at the current turtle position.
      java.lang.String getPixelColorStr()
      Returns the color of the pixel at the current turtle position as X11 string.
      Playground getPlayground()
      Returns the turtle's Playground.
      java.awt.geom.Point2D.Double getPos()
      Returns the current playground bounded turtle position.
      static java.lang.String getPropLocation()
      Returns properties file location.
      double getSpeed()
      Returns the current turtle animation speed.
      TurtleFactory getTurtleFactory()
      Returns the turtle's TurtleFactory.
      double getX()
      Returns the current playground bounded turtle's x-coordinate.
      double getY()
      Returns the current playground bounded turtle's y-coordinate.
      double heading()
      Returns the turtle's heading.
      double heading(double degrees)
      Sets the turtle's heading (zero to north, clockwise positive).
      Turtle hideTurtle()
      Hide the Turtle.
      Turtle home()
      Moves the turtle back "home", i.e. to coordinates (0, 0), heading north.
      Turtle ht()
      Hides the Turtle.
      boolean isClip()
      Reports if the turtle is in clip mode.
      static boolean isDisposed()
      Checks if the turtle frame was disposed or released.
      boolean isHidden()
      Reports if the turtle is hidden or shown.
      boolean isPenUp()
      Reports if the pen is up.
      boolean isWrap()
      Requests if the turtle is in wrap mode.
      Turtle label(java.lang.String text)
      Draw the specified text at the current turtle position using the current text font (default SansSerif, Font.PLAIN, 24).
      Turtle left(double degrees)
      Same as lt()
      Turtle leftCircle(double radius)
      Draws a left-oriented circle from the current position with turtle's heading tangent direction and given radius.
      Turtle lt(double degrees)
      Turns the turtle to the left.
      Turtle moveTo(double x, double y)
      Moves the turtle to the given position.
      Turtle moveTo(java.awt.geom.Point2D.Double pt)
      Moves the turtle to the given position.
      Turtle openDot(double radius)
      Draws an open dot (unfilled circle) with line width 1 at the current turtle position using the current pen color.
      Turtle pd()
      Lowers the turtle's pen, so the trace is drawn.
      Turtle pe()
      Sets the pen color to the background color, so existing traces are erased.
      Turtle penDown()
      Same as pd().
      Turtle penErase()
      Same as pe().
      Turtle penUp()
      Same as pu().
      int penWidth()
      Returns the current pen width.
      Turtle penWidth(int width)
      Sets the line width of the traces.
      Turtle popState()
      Retrieves the last state from the turtle state buffer and sets the turtle properties accordingly.
      boolean print(TPrintable tp)
      Same as print(tp, scale) with scale = 1.
      boolean print(TPrintable tp, double scale)
      Prints the graphics context to an attached printer with the given magnification scale factor.
      boolean printScreen()
      Same as printScreen(scale) with scale = 1.
      boolean printScreen(double scale)
      Print the turtle's current playground with given scale.
      Turtle pu()
      Lifts the turtle's pen up, so no trace is drawn.
      Turtle pushState()
      Saves the current turtle state in a turtle state buffer.
      void repaint()
      Performs manual repainting when automatic repainting is disabled.
      Turtle right(double degrees)
      Same as rt().
      Turtle rightCircle(double radius)
      Draws a right-oriented circle from the current position with turtle's heading tangent direction and given radius.
      Turtle rt(double degrees)
      Turns the turtle to the right.
      Turtle setAngleResolution(int resolution)
      Sets the angle resolution when animating the turtle rotation.
      Turtle setColor(java.awt.Color color)
      Sets the turtle's color.
      Turtle setColor(java.lang.String colorStr)
      Sets the turtle's color as string.
      Turtle setCursor(int cursorType)
      Sets the mouse cursor image.
      java.awt.Dimension setCustomCursor(java.lang.String cursorImage)
      Same as setCustomCursor(cursorImage, hotSpot) with hotSpot in center of image.
      java.awt.Dimension setCustomCursor(java.lang.String cursorImage, java.awt.Point hotSpot)
      Sets the mouse cursor image to a custom icon.
      Turtle setFillColor(java.awt.Color color)
      Sets the fill color for fill().
      Turtle setFillColor(java.lang.String colorStr)
      Sets the fill color for fill() using the color as string.
      Turtle setFont(java.awt.Font font)
      Sets the current text font (default: Font("SansSerif", Font.PLAIN, 24).
      Turtle setFont(java.lang.String fontName, int style, int size)
      Sets the current text font (default: Font("SansSerif", Font.PLAIN, 24).
      Turtle setFontSize(int size)
      Sets the font size.
      Turtle setFontStyle(int style)
      Sets the font style.
      Turtle setH(double degrees)
      Sets the turtle's heading (zero to north, clockwise positive).
      Turtle setHeading(double degrees)
      Same as setH().
      Turtle setLineWidth(double lineWidth)
      Sets the line width of the traces.
      Turtle setPenColor(java.awt.Color color)
      Sets the turtle's pen color.
      Turtle setPenColor(java.lang.String colorStr)
      Sets the turtle's pen color as string.
      Turtle setPos(double x, double y)
      Puts the turtle to a new position without drawing a trace.
      Turtle setPos(java.awt.geom.Point2D.Double pt)
      Puts the turtle to a new position without drawing a trace.
      Turtle setRandomHeading()
      Sets the turtle's heading to a random value between 0 and 360 degrees.
      Turtle setRandomPos(double width, double height)
      Puts the turtle to a new random position in a rectangle area with given width and height (center in the middle of the playground) without drawing a trace.
      Turtle setScreenPos(java.awt.Point pt)
      Puts the Turtle to a new screen position without drawing a trace.
      Turtle setScreenX(int x)
      Puts the turtle to a new position with the given screen x-coordinates without drawing a trace.
      Turtle setScreenY(int y)
      Puts the turtle to a new position with the given screen y-coordinates without drawing a trace.
      void setStatusText(java.lang.String text)
      Replaces the text in the status bar by the given text using the current JOptionPane font and color.
      void setStatusText(java.lang.String text, java.awt.Font font, java.awt.Color color)
      Replaces the text in the status bar by the given text using the given font and text color.
      void setTitle(java.lang.String text)
      Sets the title of turtle's playground
      Turtle setX(double x)
      Puts the turtle to a new position with the given x-coordinates without drawing a trace.
      Turtle setY(double y)
      Puts the turtle to a new position with the given y-coordinates without drawing a trace.
      void showStatusBar(boolean show)
      Shows/hides the status bar.
      Turtle showTurtle()
      Same as st().
      static void sleep(int time)
      Delays execution for the given amount of time (in ms).
      Turtle speed(double speed)
      Sets the turtle's speed.
      Turtle st()
      Makes a hidden turtle visible.
      Turtle stampTurtle()
      Shows a turtle image (a clone) at the current position/heading.
      Turtle stampTurtle(java.awt.Color color)
      Shows a turtle image (a clone) with given color at the current position/heading.
      Turtle stampTurtle(java.lang.String colorStr)
      Shows a turtle image (a clone) with given color as string at the current position/heading.
      Turtle startPath()
      Starts recording the path vertexes where the turtle moves.
      Turtle toBottom()
      Puts the turtle to the bottom, so other turtles will be drawn above.
      static java.awt.Color toColor(java.lang.String colorStr)
      Returns the Color reference for the given color as string.
      Turtle toTop()
      Puts the turtle to the top, so other turtles will be drawn below.
      java.awt.geom.Point2D.Double toTurtlePos(int x, int y)
      Converts from screen coordinates to turtle coordinates.
      java.awt.geom.Point2D.Double toTurtlePos(java.awt.Point p)
      Converts from screen coordinates to turtle coordinates.
      double toTurtleX(int x)
      Converts from screen coordinates to turtle coordinates.
      double toTurtleY(int y)
      Converts from screen coordinates to turtle coordinates.
      double towards(double x, double y)
      Returns the direction (heading) to a given position.
      double towards(java.awt.geom.Point2D.Double pt)
      Returns the direction (heading) to a given position.
      static java.lang.String version()
      Returns libarary version information.
      Turtle viewingMoveTo(double x, double y)
      Moves the turtle to the new relative position.
      Turtle viewingSetPos(double x, double y)
      Puts the turtle to a new relative position without drawing a trace.
      Turtle wrap()
      Sets the turtle to wrap mode.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • BLACK

        public static final java.awt.Color BLACK
      • BLUE

        public static final java.awt.Color BLUE
        Short for Color.BLUE.
      • CYAN

        public static final java.awt.Color CYAN
        Short for Color.CYAN.
      • DKGRAY

        public static final java.awt.Color DKGRAY
        Short for Color.GRAY.
      • GRAY

        public static final java.awt.Color GRAY
        Short for Color.GRAY.
      • GREEN

        public static final java.awt.Color GREEN
        Short for Color.GREEN.
      • LTGRAY

        public static final java.awt.Color LTGRAY
        Short for Color.LIGHT_GRAY.
      • MAGENTA

        public static final java.awt.Color MAGENTA
        Short for Color.MAGENTA.
      • RED

        public static final java.awt.Color RED
        Short for Color.RED.
      • WHITE

        public static final java.awt.Color WHITE
        Short for Color.WHITE.
      • YELLOW

        public static final java.awt.Color YELLOW
        Short for Color.YELLOW.
      • STANDARDFRAME

        public static int STANDARDFRAME
        Mode attribute for normal turtle applications (default, value: 0). When the title bar close button is hit, System.exit() is called to terminate the application.
      • APPLETFRAME

        public static int APPLETFRAME
        Mode attribute for turtle applets in a standalone window (value: 1).
      • CLEAR_ON_CLOSE

        public static int CLEAR_ON_CLOSE
        Mode attribute for a turtle frame that calls Turtle.clear() when the close button is hit (value: 2).
      • ASK_ON_CLOSE

        public static int ASK_ON_CLOSE
        Mode attribute for a turtle frame that opens a confirm dialog when the close button is hit (value: 3). If accepted, System.exit() is called to terminate the application.
      • DISPOSE_ON_CLOSE

        public static int DISPOSE_ON_CLOSE
        Mode attribute for a turtle frame that closes the turtle frame and releases grapics resources (value: 4), but does not call System.exit().
      • RELEASE_ON_CLOSE

        public static int RELEASE_ON_CLOSE
        Mode attribute for a turtle frame that closes the turtle frame by disposing all resources (value: 5), but does not call System.exit(). Every public turtle method throws a runtime exception if called after the frame is closed.
      • NOTHING_ON_CLOSE

        public static int NOTHING_ON_CLOSE
        Mode attribute for a turtle frame that does nothing when the close button is hit (value: -1).
    • Constructor Detail

      • Turtle

        public Turtle()
        Creates a new turtle in its own new window. If turtlegraphics.properties is found, defaults are specified there.
      • Turtle

        public Turtle(boolean show)
        Creates a new turtle with specified visibility in its own new window.
        Parameters:
        show - if true, the turtle is visible when created; otherwise it remains hidden until showTurtle() or st() is called
      • Turtle

        public Turtle(java.awt.Color color)
        Creates a new turtle with specified color in its own new window. If turtlegraphics.properties is found, defaults are specified there, but TurtleColor key is ignored.
        Parameters:
        color - the turtle color (default: cyan)
      • Turtle

        public Turtle(java.lang.String colorStr)
        Creates a new turtle with specified color as string in its own new window. The X11 color names are supported. If turtlegraphics.properties is found, defaults are specified there, but TurtleColor key is ignored.
        Parameters:
        colorStr - the turtle color (default: cyan); if the string is not one of the predefined values, the given string is interpreted as filename for a custom turtle shape. If the image file can't be loaded the default turtle color is used
      • Turtle

        public Turtle(javax.swing.JMenuBar menuBar,
              java.awt.Color color)
        Creates a new turtle with specified color in its own new window with the given menu. If turtlegraphics.properties is found, defaults are specified there, but TurtleColor key is ignored.
        Parameters:
        menuBar - a reference to the JMenuBar instance
        color - the turtle color (default: cyan)
      • Turtle

        public Turtle(TurtleContainer turtleContainer)
        Creates a new turtle in the given TurtleContainer. If turtlegraphics.properties is found, all entries are ignored.
        Parameters:
        turtleContainer - a reference to the TurtleContainer where the turtle lives
      • Turtle

        public Turtle(TurtlePane turtlePane)
        Creates a new turtle in the given TurtlePane. If turtlegraphics.properties is found, all entries are ignored.
        Parameters:
        turtlePane - a reference to the TurtlePane where the turtle lives.
      • Turtle

        public Turtle(TurtleContainer turtleContainer,
              boolean show)
        Creates a new turtle with specified visibility in the given TurtleContainer. If turtlegraphics.properties is found, all entries are ignored.
        Parameters:
        turtleContainer - a reference to the TurtleContainer where the turtle lives
        show - if true, the turtle is visible when created; otherwise it remains hidden until showTurtle() or st() is called
      • Turtle

        public Turtle(TurtleContainer turtleContainer,
              java.awt.Color color)
        Creates a new turtle with specified color in the given TurtleContainer. If turtlegraphics.properties is found, all entries are ignored.
        Parameters:
        turtleContainer - a reference to the TurtleContainer where the turtle lives
        color - the turtle color (default: cyan)
      • Turtle

        public Turtle(TurtleContainer turtleContainer,
              java.lang.String colorStr)
        Creates a new turtle with specified color as a string in the given TurtleContainer. The X11 color names are supported. If turtlegraphics.properties is found, all entries are ignored.
        Parameters:
        turtleContainer - a reference to the TurtleContainer where the turtle lives
        colorStr - the turtle color (default: cyan); if the string is not one of the predefined values, the given string is interpreted as filename for a custom turtle shape. If the image file can't be loaded the default turtle color is used
      • Turtle

        public Turtle(Turtle otherTurtle)
        Creates a new turtle in the same TurtleContainer (window) as the given turtle. If turtlegraphics.properties is found, defaults for the turtle are specified there.
        Parameters:
        otherTurtle - the turtle from where to take the window
      • Turtle

        public Turtle(Turtle otherTurtle,
              boolean show)
        Creates a new turtle in the same TurtleContainer (window) as the given turtle and specifies its visibility. If turtlegraphics.properties is found, defaults for the turtle are specified there.
        Parameters:
        otherTurtle - the turtle from where to take the window
        show - if true, the turtle is visible when created; otherwise it remains hidden until showTurtle() or st() is called
      • Turtle

        public Turtle(Turtle otherTurtle,
              java.awt.Color color)
        Creates a new turtle with the specified color in the same TurtleContainer (window) as the given turtle. If turtlegraphics.properties is found, defaults for the turtle are specified there, but TurtleColor key is ignored.
        Parameters:
        otherTurtle - the turtle from where to take the window
        color - the turtle color (default: cyan)
      • Turtle

        public Turtle(Turtle otherTurtle,
              java.lang.String colorStr)
        Creates a new turtle with specified color as string in the same TurtleContainer (window) as the given turtle. The X11 color names are supported. If turtlegraphics.properties is found, defaults are specified there, but TurtleColor key is ignored.
        Parameters:
        otherTurtle - the turtle from where to take the window
        colorStr - the turtle color (default: cyan); if the string is not one of the predefined values, the given string is interpreted as filename for a custom turtle shape. If the image file can't be loaded the default turtle color is used
    • Method Detail

      • toTurtlePos

        public java.awt.geom.Point2D.Double toTurtlePos(java.awt.Point p)
        Converts from screen coordinates to turtle coordinates.
        Parameters:
        p - the point in pixel coordinates (default 0..400)
        Returns:
        the turtle coordinates
      • toTurtlePos

        public java.awt.geom.Point2D.Double toTurtlePos(int x,
                                               int y)
        Converts from screen coordinates to turtle coordinates.
        Parameters:
        x - the x-coordinate in pixel (default 0..400)
        y - the y-coordinate in pixel (default 0..400)
        Returns:
        the turtle coordinates
      • toTurtleX

        public double toTurtleX(int x)
        Converts from screen coordinates to turtle coordinates.
        Parameters:
        x - the x-coordinate in pixels
        Returns:
        the turtle x-coordinate
      • toTurtleY

        public double toTurtleY(int y)
        Converts from screen coordinates to turtle coordinates.
        Parameters:
        y - the y-coordinate in pixels
        Returns:
        the turtle y-coordinate
      • getFrame

        public TurtleFrame getFrame()
        Returns the turtle's TurtleFrame (derivated from JFrame).
        Returns:
        a reference to the TurtleFrame where the turtle lives
      • addMouseListener

        public void addMouseListener(java.awt.event.MouseListener listener)
        Adds the specified mouse listener to receive mouse events.
        Parameters:
        listener - the registered MouseListener
      • addMouseMotionListener

        public void addMouseMotionListener(java.awt.event.MouseMotionListener listener)
        Adds the specified mouse motion listener to receive mouse motion events.
        Parameters:
        listener - the registered MouseMotionListener
      • addMouseHitListener

        public void addMouseHitListener(MouseHitListener listener)
        Adds the specified mouse-hit listener to receive mouse events.
        Parameters:
        listener - the registered MouseHitListener
      • addMouseHitXListener

        public void addMouseHitXListener(MouseHitXListener listener)
        Adds the specified mouse-hit-x listener to receive mouse events.
        Parameters:
        listener - the registered MouseHitXListener
      • addKeyListener

        public void addKeyListener(java.awt.event.KeyListener listener)
        Adds the specified key listener to receive key events. (Not allowed for embedded applets.)
        Parameters:
        listener - the registered KeyListener
      • addWindowListener

        public void addWindowListener(java.awt.event.WindowListener listener)
        Adds the specified window listener to receive window events. (Not allowed for embedded applets.)
        Parameters:
        listener - the registered WindowListener
      • addWindowFocusListener

        public void addWindowFocusListener(java.awt.event.WindowFocusListener listener)
        Adds the specified window focus listener to receive window focus events. (Not allowed for embedded applets.)
        Parameters:
        listener - the registered WindowFocusListener
      • addComponentListener

        public void addComponentListener(java.awt.event.ComponentListener listener)
        Adds the specified component listener to receive component events. (Not allowed for embedded applets.)
        Parameters:
        listener - the registered ComponentListener
      • addFocusListener

        public void addFocusListener(java.awt.event.FocusListener listener)
        Adds the specified focus listener to receive focus events. (Not allowed for embedded applets.)
        Parameters:
        listener - the registered FocusListener
      • beep

        public Turtle beep()
        Emits a 'beep'. Fails if no standard speaker available.
        Returns:
        the Turtle reference to allow chaining
      • setAngleResolution

        public Turtle setAngleResolution(int resolution)
        Sets the angle resolution when animating the turtle rotation. The parameter specifies the number of images for a 360 degrees rotation (default 72, e.g. 5 degrees increment).
        Parameters:
        resolution - the new angle resolution (default: 72)
        Returns:
        the Turtle reference to allow chaining
      • getTurtleFactory

        public TurtleFactory getTurtleFactory()
        Returns the turtle's TurtleFactory.
        Returns:
        the TurtleFactory reference
      • getPlayground

        public Playground getPlayground()
        Returns the turtle's Playground.
        Returns:
        the Playground reference
      • getSpeed

        public double getSpeed()
        Returns the current turtle animation speed.
        Returns:
        the turtle speed (turtle coordinates per seconds, -1 if no animation)
      • _getX

        public double _getX()
        Returns the current unbounded turtle's x-coordinate.
        Returns:
        the x-coordinate (not bounded to the playground, even even when wrapping is on)
      • _getY

        public double _getY()
        Returns the current unbounded turtle's y-coordinate.
        Returns:
        the y-coordinate (not bounded to the playground, even even when wrapping is on)
      • getX

        public double getX()
        Returns the current playground bounded turtle's x-coordinate. If the turtle is outside the playground and wrapping is on, the coordinate is mapped to the playground.
        Returns:
        the x-coordinate of the visible turtle
      • getY

        public double getY()
        Returns the current playground bounded turtle's y-coordinate. If the turtle is outside the playground and wrapping is on, the coordinate is mapped to the playground.
        Returns:
        the y-coordinate of the visible turtle
      • _getPos

        public java.awt.geom.Point2D.Double _getPos()
        Returns the current unbounded turtle position.
        Returns:
        the turtle coordinates (not bounded to the playground, even even when wrapping is on)
      • getPos

        public java.awt.geom.Point2D.Double getPos()
        Returns the current playground bounded turtle position. If the turtle is outside the playground and wrapping is on, the position is mapped to the playground.
        Returns:
        the turtle coordinates of the visible turtle
      • setRandomPos

        public Turtle setRandomPos(double width,
                          double height)
        Puts the turtle to a new random position in a rectangle area with given width and height (center in the middle of the playground) without drawing a trace.
        Parameters:
        width - the width of the rectangular area
        height - the height of the rectangular
        Returns:
        the Turtle reference to allow chaining
      • setPos

        public Turtle setPos(double x,
                    double y)
        Puts the turtle to a new position without drawing a trace.
        Parameters:
        x - the x-coordinate of the new position
        y - the y-coordinate of the new position
        Returns:
        the Turtle reference to allow chaining
      • setPos

        public Turtle setPos(java.awt.geom.Point2D.Double pt)
        Puts the turtle to a new position without drawing a trace.
        Parameters:
        pt - the turtle coordinates of the new position
        Returns:
        the Turtle reference to allow chaining
      • setScreenPos

        public Turtle setScreenPos(java.awt.Point pt)
        Puts the Turtle to a new screen position without drawing a trace.
        Parameters:
        pt - the screen coordinates of the new position (coordinate system with origin at upper left vertex of playground, same coordinate increments as turtle coordinates)
        Returns:
        the Turtle reference to allow chaining
      • setScreenX

        public Turtle setScreenX(int x)
        Puts the turtle to a new position with the given screen x-coordinates without drawing a trace. (Coordinate system with origin at upper left vertex of playground, same coordinate increments as turtle coordinates.)
        Returns:
        the Turtle reference to allow chaining
      • setScreenY

        public Turtle setScreenY(int y)
        Puts the turtle to a new position with the given screen y-coordinates without drawing a trace. (Coordinate system with origin at upper left vertex of playground, same coordinate increments as turtle coordinates.)
        Returns:
        the Turtle reference to allow chaining
      • setX

        public Turtle setX(double x)
        Puts the turtle to a new position with the given x-coordinates without drawing a trace.
        Returns:
        the Turtle reference to allow chaining
      • setY

        public Turtle setY(double y)
        Puts the turtle to a new position with the given y-coordinates without drawing a trace.
        Returns:
        the Turtle reference to allow chaining
      • ht

        public Turtle ht()
        Hides the Turtle. If there is only one turte, the speed is set to -1 so there is no Turtle animation at all. Hiding the Turtle speeds up the graphics enormously.
        Returns:
        the Turtle reference to allow chaining
      • hideTurtle

        public Turtle hideTurtle()
        Hide the Turtle. Same as ht().
        Returns:
        the Turtle reference to allow chaining
      • st

        public Turtle st()
        Makes a hidden turtle visible.
        Returns:
        the Turtle reference to allow chaining
      • showTurtle

        public Turtle showTurtle()
        Same as st().
        Returns:
        the Turtle reference to allow chaining
      • isHidden

        public boolean isHidden()
        Reports if the turtle is hidden or shown.
        Returns:
        true if the turtle is hidden; otherwise false
      • setH

        public Turtle setH(double degrees)
        Sets the turtle's heading (zero to north, clockwise positive).
        Parameters:
        degrees - the compass direction (in degrees)
        Returns:
        the Turtle reference to allow chaining
      • setHeading

        public Turtle setHeading(double degrees)
        Same as setH().
        Returns:
        the Turtle reference to allow chaining
      • setRandomHeading

        public Turtle setRandomHeading()
        Sets the turtle's heading to a random value between 0 and 360 degrees.
        Returns:
        the Turtle reference to allow chaining
      • heading

        public double heading()
        Returns the turtle's heading.
        Returns:
        the compass direction (degrees, zero to north, clockwise positive)
      • heading

        public double heading(double degrees)
        Sets the turtle's heading (zero to north, clockwise positive).
        Parameters:
        degrees - the compass direction (in degrees)
        Returns:
        the old (previous) value
      • speed

        public Turtle speed(double speed)
        Sets the turtle's speed.
        Parameters:
        speed - the speed in turtle coordinates (pixels) per second (up to a certain limit depending on the hardware). Zero will be set to 1 (very slow). Less than zero will be set to -1 (no animation)
        Returns:
        the turtle reference reference to allow chaining.
      • lt

        public Turtle lt(double degrees)
        Turns the turtle to the left.
        Parameters:
        degrees - the rotation angle (in degrees)
        Returns:
        the Turtle reference to allow chaining
      • left

        public Turtle left(double degrees)
        Same as lt()
        Returns:
        the Turtle reference to allow chaining
      • rt

        public Turtle rt(double degrees)
        Turns the turtle to the right.
        Parameters:
        degrees - the rotation angle (in degrees)
        Returns:
        the Turtle reference to allow chaining
      • right

        public Turtle right(double degrees)
        Same as rt().
        Parameters:
        degrees - the rotation angle (in degrees)
        Returns:
        the Turtle reference to allow chaining
      • fd

        public Turtle fd(double distance)
        Moves the turtle forwards.
        Parameters:
        distance - the moving distance in turtle coordinates. Negative values move the turtle backwards.
        Returns:
        the Turtle reference to allow chaining
      • forward

        public Turtle forward(double distance)
        Same as fd().
        Parameters:
        distance - the moving distance in turtle coordinates. Negative values move the turtle backwards.
        Returns:
        the Turtle reference to allow chaining
      • bk

        public Turtle bk(double distance)
        Moves the turtle backwards.
        Parameters:
        distance - the moving distance in turtle coordinates. Negative values move the turtle forwards.
        Returns:
        the Turtle reference to allow chaining
      • back

        public Turtle back(double distance)
        Same as bk().
        Parameters:
        distance - the moving distance in turtle coordinates. Negative values move the turtle forwards.
        Returns:
        the Turtle reference to allow chaining
      • distance

        public double distance(double x,
                      double y)
        Returns the distance between the current turtle position and the given position,
        Parameters:
        x - the x-coordinate of the target position
        y - the y-coordinate of the target position
        Returns:
        distance between turtle and target (in turtle coordinates)
      • distance

        public double distance(java.awt.geom.Point2D.Double pt)
        Returns the distance between the current turtle position and the given position,
        Parameters:
        pt - the coordinate of the target position
        Returns:
        distance between turtle and target (in turtle coordinates)
      • leftCircle

        public Turtle leftCircle(double radius)
        Draws a left-oriented circle from the current position with turtle's heading tangent direction and given radius. (Actually a polygon with 36 sides is drawn.)
        Parameters:
        radius - the radius of the circle (in turtle coordinates)
        Returns:
        the Turtle reference to allow chaining
      • rightCircle

        public Turtle rightCircle(double radius)
        Draws a right-oriented circle from the current position with turtle's heading tangent direction and given radius. (Actually a polygon with 36 sides is drawn.)
        Parameters:
        radius - the radius of the circle (in turtle coordinates)
        Returns:
        the Turtle reference to allow chaining
      • pu

        public Turtle pu()
        Lifts the turtle's pen up, so no trace is drawn.
        Returns:
        the Turtle reference to allow chaining
      • penUp

        public Turtle penUp()
        Same as pu().
        Returns:
        the Turtle reference to allow chaining
      • pd

        public Turtle pd()
        Lowers the turtle's pen, so the trace is drawn.
        Returns:
        the Turtle reference to allow chaining
      • penDown

        public Turtle penDown()
        Same as pd().
        Returns:
        the Turtle reference to allow chaining
      • isPenUp

        public boolean isPenUp()
        Reports if the pen is up.
        Returns:
        true if the pen is up; otherwise false
      • getPen

        public Pen getPen()
        Return the turtle's Pen reference.
        Returns:
        a reference to the Pen instance
      • penWidth

        public Turtle penWidth(int width)
        Sets the line width of the traces. (In wrap mode, larger lines may not be cut cleanly at the window border.)
        Parameters:
        width - the line width in pixels
        Returns:
        the Turtle reference to allow chaining
      • penWidth

        public int penWidth()
        Returns the current pen width.
        Returns:
        the pen width in pixels
      • setLineWidth

        public Turtle setLineWidth(double lineWidth)
        Sets the line width of the traces. (In wrap mode, larger lines may not be cut cleanly at the window border.)
        Parameters:
        lineWidth - the line width in turtle coordinates (pixels)
        Returns:
        the Turtle reference to allow chaining
      • setColor

        public Turtle setColor(java.awt.Color color)
        Sets the turtle's color.
        Parameters:
        color - the new turtle color. If a custom turtle image is used, the method does nothing
        Returns:
        the Turtle reference to allow chaining
      • setColor

        public Turtle setColor(java.lang.String colorStr)
        Sets the turtle's color as string. The X11 color names are supported.
        Parameters:
        colorStr - the turtle's color (default: cyan); if the string is not one of the predefined values or a custom turtle image is used, the color is not modified; if a custom turtle image is used, the method does nothing
        Returns:
        the Turtle reference to allow chaining
      • toColor

        public static java.awt.Color toColor(java.lang.String colorStr)
        Returns the Color reference for the given color as string. The X11 color names are supported.
        Returns:
        the Color reference or null, if the given color is not one of the predefined values
      • setFillColor

        public Turtle setFillColor(java.awt.Color color)
        Sets the fill color for fill(). The fill color for fillToPoint(), fillToHorizontal(), fillToVertical() is not affected.
        Parameters:
        color - the new fill color (default: Color.blue).
        Returns:
        the Turtle reference to allow chaining
      • setFillColor

        public Turtle setFillColor(java.lang.String colorStr)
        Sets the fill color for fill() using the color as string. The fill color for fillToPoint(), fillToHorizontal(), fillToVertical() is not affected. The X11 color names are supported.
        Parameters:
        colorStr - the fill color (default: blue); if the string is not one of the predefined values, the color is not modified
        Returns:
        the Turtle reference to allow chaining
      • getFillColor

        public java.awt.Color getFillColor()
        Returns the turtle's current fill color.
        Returns:
        the fill color
      • getFillColorStr

        public java.lang.String getFillColorStr()
        Returns the X11 color string of the turtle's current fill color.
        Returns:
        the fill color string (lowercase); empty if not an X11 color
      • getColor

        public java.awt.Color getColor()
        Returns the turtle's current color.
        Returns:
        the turtle color
      • getColorStr

        public java.lang.String getColorStr()
        Returns the X11 color string of the turtle's current color.
        Returns:
        the turtle color string (lowercase); empty if not an X11 color
      • setPenColor

        public Turtle setPenColor(java.awt.Color color)
        Sets the turtle's pen color.
        Parameters:
        color - the new pen color
        Returns:
        the Turtle reference to allow chaining
      • setPenColor

        public Turtle setPenColor(java.lang.String colorStr)
        Sets the turtle's pen color as string. The X11 color names are supported.
        Parameters:
        colorStr - the pen color (default: blue); if the string is not one of the predefined values, the color is not modified
        Returns:
        the Turtle reference to allow chaining
      • getPenColor

        public java.awt.Color getPenColor()
        Returns the turtle's pen color.
        Returns:
        the pen color
      • getPenColorStr

        public java.lang.String getPenColorStr()
        Returns the X11 color string of the turtle's current pen color.
        Returns:
        the turtle pen color string (lowercase); empty if not an X11 color
      • home

        public Turtle home()
        Moves the turtle back "home", i.e. to coordinates (0, 0), heading north. Other turtle properties are not modified.
        Returns:
        the Turtle reference to allow chaining
      • pe

        public Turtle pe()
        Sets the pen color to the background color, so existing traces are erased.
        Returns:
        the Turtle reference to allow chaining
      • penErase

        public Turtle penErase()
        Same as pe().
        Returns:
        the Turtle reference to allow chaining
      • stampTurtle

        public Turtle stampTurtle()
        Shows a turtle image (a clone) at the current position/heading.
        Returns:
        the Turtle reference to allow chaining
      • stampTurtle

        public Turtle stampTurtle(java.awt.Color color)
        Shows a turtle image (a clone) with given color at the current position/heading. If the turtle has a custom image, the clone's image is the same and the given color is not used.
        Returns:
        the Turtle reference to allow chaining
      • stampTurtle

        public Turtle stampTurtle(java.lang.String colorStr)
        Shows a turtle image (a clone) with given color as string at the current position/heading. If the turtle has a custom image, the clone's image is the same and the given color is not used.
        Returns:
        the Turtle reference to allow chaining
      • towards

        public double towards(double x,
                     double y)
        Returns the direction (heading) to a given position.
        Parameters:
        x - the x-coordinate of the target
        y - the x-coordinate of the target
        Returns:
        the angle from the current turtle position to the given target point (in degrees, clockwise positive measured from north)
      • towards

        public double towards(java.awt.geom.Point2D.Double pt)
        Returns the direction (heading) to a given position.
        Parameters:
        pt - the coordinates of the target
        Returns:
        the angle from the current turtle position to the given target point (in degrees, clockwise positive measured from north)
      • toBottom

        public Turtle toBottom()
        Puts the turtle to the bottom, so other turtles will be drawn above.
        Returns:
        the Turtle reference to allow chaining
      • toTop

        public Turtle toTop()
        Puts the turtle to the top, so other turtles will be drawn below.
        Returns:
        the Turtle reference to allow chaining
      • clip

        public Turtle clip()
        Sets the turtle to clip mode. In clip mode the turtle may move outside the window.
        Returns:
        the Turtle reference to allow chaining
      • wrap

        public Turtle wrap()
        Sets the turtle to wrap mode. In wrap mode the turtle remains visible in the window, i.e. when it leaves the window on one side, it reappears on the opposite side (torus symmetry).
        Returns:
        the Turtle reference to allow chaining
      • isClip

        public boolean isClip()
        Reports if the turtle is in clip mode.
        Returns:
        true if in clip mode; otherwise false
      • isWrap

        public boolean isWrap()
        Requests if the turtle is in wrap mode.
        Returns:
        true if in wrap mode; otherwise false
      • fill

        public Turtle fill()
        Fills a closed region (flood fill) with the current fill color (default: Color.blue). A region is bounded by lines of any color different than the pixel color at the current turtle position and by the border of the window. If this pixel color is the same as the fill color, nothing is done, unless one of the 8 neighbor pixels has a different color.
        Returns:
        the Turtle reference to allow chaining
      • fill

        public Turtle fill(double x,
                  double y)
        /** Fills a closed region (flood fill) with the current fill color (default: Color.blue) as if the turtle where at the given coordinates. A region is bounded by lines of any color different to the pixel color at the given coordinates and by the border of the window. If this pixel color is the same as the fill color, nothing is done, unless one of the 8 neighbor pixels has a different color.
        Parameters:
        x - the x-coordinate of the inner point
        y - the y-coordinate of the inner point
        Returns:
        the Turtle reference to allow chaining
      • label

        public Turtle label(java.lang.String text)
        Draw the specified text at the current turtle position using the current text font (default SansSerif, Font.PLAIN, 24).
        Returns:
        the Turtle reference to allow chaining
      • setFont

        public Turtle setFont(java.awt.Font font)
        Sets the current text font (default: Font("SansSerif", Font.PLAIN, 24).
        Parameters:
        font - the new text font.
        Returns:
        the Turtle reference to allow chaining
      • setFont

        public Turtle setFont(java.lang.String fontName,
                     int style,
                     int size)
        Sets the current text font (default: Font("SansSerif", Font.PLAIN, 24). If you want to know what fonts are available on your system, call getAvailableFontFamilies(). See java.awt.Font for more information about fontName, style and size.
        Parameters:
        fontName - the name of the font
        style - the font style id
        size - the font size
        Returns:
        the Turtle reference to allow chaining
      • setFontSize

        public Turtle setFontSize(int size)
        Sets the font size.
        Parameters:
        size - the font size
        Returns:
        the Turtle reference to allow chaining
      • setFontStyle

        public Turtle setFontStyle(int style)
        Sets the font style.
        Parameters:
        style - the font style id
        Returns:
        the Turtle reference to allow chaining
      • getAvailableFontFamilies

        public static java.lang.String[] getAvailableFontFamilies()
        Provides information about all font families currently available on your system. Each font name is a string packed into a array of strings.
      • getFont

        public java.awt.Font getFont()
        Returns the current font.
        Returns:
        the text font
      • clone

        public java.lang.Object clone()
        Creates a partial clone of the turtle. The playground, color or image, position and heading are the same. Other properties are those of a new turtle.
        Overrides:
        clone in class java.lang.Object
        Returns:
        the cloned object reference as an Object type, because it overrides Object.clone(). You may cast it to a Turtle
      • antiAliasing

        public Turtle antiAliasing(boolean on)
        Sets anti-aliasing (for the turtle trace buffer) on or off. This may result in an better image quality, especially for filling operations (platform dependant).
        Returns:
        the Turtle reference to allow chaining
      • print

        public boolean print(TPrintable tp,
                    double scale)
        Prints the graphics context to an attached printer with the given magnification scale factor. scale = 1 will print on standard A4 format paper.
        The given tp must implement the GPrintable interface, e.g. the single method void draw(), where all the drawing into the GPanel must occur. Be aware the turtle(s) state (position, direction, etc.) must be reinitialized, because draw() is called several times by the printing system. A standard printer dialog is shown before printing is started. Only turtle traces are printed.
        Example:
        import ch.aplu.turtle.*;

        public class PrintTest implements TPrintable
        {
        private Turtle t = new Turtle();

        public PrintTest()
        {
        draw(); // Draw on screen
        t.print(this); // Draw on printer
        }

        public void draw()
        {
        t.home(); // Needed for initialization
        for (int i = 0; i < 5; i++)
        t.fd(20).rt(90).fd(20).lt(90);
        }

        public static void main(String[] args)
        {
        new PrintTest();
        }
        }
        Parameters:
        tp - a TPrintable reference
        scale - the scaling factor
      • print

        public boolean print(TPrintable tp)
        Same as print(tp, scale) with scale = 1.
        Parameters:
        tp - a TPrintable reference
      • printScreen

        public boolean printScreen(double scale)
        Print the turtle's current playground with given scale.
        Parameters:
        scale - the scaling factor
      • printScreen

        public boolean printScreen()
        Same as printScreen(scale) with scale = 1.
      • clear

        public Turtle clear()
        Clears the turtle's playground. All turtle images, traces and text are erased, and the turtles remain (hidden) at their positions.
        Returns:
        the Turtle reference to allow chaining
      • clear

        public Turtle clear(java.awt.Color color)
        Clears the turtle's playground but painting it with the given color. All traces and text are erased, and the turtles remain (hidden) at their positions.
      • clear

        public Turtle clear(java.lang.String colorStr)
        Clears the turtle's playground but painting it with the given color. All traces and text are erased, and the turtles remain (hidden) at their positions. The X11 color names are supported.
        Parameters:
        colorStr - the background color (default: white); if the string is not one of the predefined values, the current background color is used
      • clean

        public Turtle clean()
        Clears the turtle's playground. All traces and text are erased, but the turtles remain (visible) at their positions.
      • clean

        public Turtle clean(java.awt.Color color)
        Clears the turtle's playground but painting it with the given color. All traces and text are erased, but the turtles remain (visible) at their positions.
      • clean

        public Turtle clean(java.lang.String colorStr)
        Clears the turtle's playground but painting it with the given color. All traces and text are erased, but the turtles remain (visible) at their positions. The X11 color names are supported.
        Parameters:
        colorStr - the background color (default: white); if the string is not one of the predefined values, the current background color is used
      • _sleep

        public void _sleep(int time)
        Non-static version of sleep(). Checks if Turtle frame is disposed and throws RuntimeException.
      • sleep

        public static void sleep(int time)
        Delays execution for the given amount of time (in ms).
      • setTitle

        public void setTitle(java.lang.String text)
        Sets the title of turtle's playground
        Parameters:
        text - the title text
      • version

        public static java.lang.String version()
        Returns libarary version information.
        Returns:
        version information
      • getPropLocation

        public static java.lang.String getPropLocation()
        Returns properties file location.
        Returns:
        properties information
      • getEnvironment

        public static java.lang.String getEnvironment()
        Returns environment information (JRE and OS).
        Returns:
        environment information
      • enableRepaint

        public void enableRepaint(boolean b)
        Enables/disables automatic repainting (default: enabled). Disabling automatic repainting and hiding the turtle speeds up the graphics enormously.
        Parameters:
        b - if true, automatic repaining is performed; otherwise repainting must be performed by calling repaint()
      • repaint

        public void repaint()
        Performs manual repainting when automatic repainting is disabled.
      • getPixelColor

        public java.awt.Color getPixelColor()
        Returns the color of the pixel at the current turtle position.
        Returns:
        the color of the pixel at the turtle position
      • getPixelColorStr

        public java.lang.String getPixelColorStr()
        Returns the color of the pixel at the current turtle position as X11 string.
        Returns:
        the X11 color (lowercase) of the pixel at the turtle position; empty if not an X11 color
      • addStatusBar

        public void addStatusBar(int height)
        Adds a status window attached at the bottom of the game grid window. The dialog has no decoration, the same width as the turtle frame and the given height.
        Parameters:
        height - the height of the status bar in pixels
      • setStatusText

        public void setStatusText(java.lang.String text)
        Replaces the text in the status bar by the given text using the current JOptionPane font and color. The text is left-justified, vertical-centered and may be multi-line. If there is no status bar, nothing happens.
        Parameters:
        text - the text to display
      • setStatusText

        public void setStatusText(java.lang.String text,
                         java.awt.Font font,
                         java.awt.Color color)
        Replaces the text in the status bar by the given text using the given font and text color. The text is left-justified, vertical-centered and may be multi-line. If there is no status bar, nothing happens.
        Parameters:
        text - the text to display
        font - the text font
        color - the text color
      • showStatusBar

        public void showStatusBar(boolean show)
        Shows/hides the status bar. If there is no status bar, nothing happens.
        Parameters:
        show - if true, the status bar is visible; otherwise invisible
      • fillToPoint

        public Turtle fillToPoint(double x,
                         double y)
        Attachs a imaginary rubber band between the turtle and the given anchor point. When the turtle now moves, the area covered by the rubber band is filled with the current pen color. Filling is on until fillOff() is called.
        Parameters:
        x - the x-coordinate of the anchor point
        y - the y-coordinate of the anchor point
        Returns:
        the Turtle reference to allow chaining
      • fillToPoint

        public Turtle fillToPoint()
        Same as fillToPoint(x, y) using the current turtle coordinates.
        Returns:
        the Turtle reference to allow chaining
      • fillToHorizontal

        public Turtle fillToHorizontal(double y)
        Draws a imaginary horizonatal line at given y-coordinate. When the turtle now moves, the trapezoidal area covered by this line and the turtle position is filled with the current pen color. Filling is on until fillOff() is called.
        Parameters:
        y - the y-coordinate of the horizontal line
        Returns:
        the Turtle reference to allow chaining
      • fillToVertical

        public Turtle fillToVertical(double x)
        Draws a imaginary vertical line at given x-coordinate. When the turtle now moves, the trapezoidal area covered by this line and the turtle position is filled with the current pen color. Filling is on until fillOff() is called.
        Parameters:
        x - the x-coordinate of the vertical line
        Returns:
        the Turtle reference to allow chaining
      • fillOff

        public Turtle fillOff()
        Stops the filling started by calling fillToPoint(), fillToHorizontal() or fillToVertical().
        Returns:
        the Turtle reference to allow chaining
      • dot

        public Turtle dot(double radius)
        Draws a dot (filled circle) at the current turtle position using the current pen color. Any turtle traces under the circle are painted anew.
        Parameters:
        radius - the radius of the circle
        Returns:
        the Turtle reference to allow chaining
      • openDot

        public Turtle openDot(double radius)
        Draws an open dot (unfilled circle) with line width 1 at the current turtle position using the current pen color.
        Parameters:
        radius - the radius of the circle
        Returns:
        the Turtle reference to allow chaining
      • moveTo

        public Turtle moveTo(double x,
                    double y)
        Moves the turtle to the given position. First the turtle turns to the new heading, then it moves forward.
        Parameters:
        x - the new turtle's x coordinate
        y - the new turtle's y coordinate
        Returns:
        the turtle reference to allow chaining
      • moveTo

        public Turtle moveTo(java.awt.geom.Point2D.Double pt)
        Moves the turtle to the given position. First the turtle turns to the new heading, then it moves forward.
        Parameters:
        pt - the turtle coordinates of the new position
        Returns:
        the turtle reference to allow chaining
      • setCursor

        public Turtle setCursor(int cursorType)
        Sets the mouse cursor image.
        Parameters:
        cursorType - one of the constants in class java.awt.Cursor
        Returns:
        the turtle reference to allow chaining
      • setCustomCursor

        public java.awt.Dimension setCustomCursor(java.lang.String cursorImage,
                                         java.awt.Point hotSpot)
        Sets the mouse cursor image to a custom icon. Normally the icon image should have size 32x32 pixels with a transparent background. The method returns the current size of the cursor. In order to avoid image transformation that reduces the image quality, the cursor image should be set to this size. From the given filename the image file is searched in the following order:
        - if application is packed into a jar archive, relative to the root of the jar archive
        - relative or absolute to current application directory
        - if filename starts with http://, from the given URL
        - if imagePath prefixed with _ relative to the root of the jar archive
        If the image can't be loaded, the cursor is unchanged
        Parameters:
        cursorImage - the path to the image file
        hotSpot - the image point that reports the mouse location (origin in upper left corner). Must be inside the custom image.
        Returns:
        the size of the cursor the system uses currently; null if the image can't be loaded
      • setCustomCursor

        public java.awt.Dimension setCustomCursor(java.lang.String cursorImage)
        Same as setCustomCursor(cursorImage, hotSpot) with hotSpot in center of image.
        Parameters:
        cursorImage - the path to the image file
        Returns:
        the size of the cursor the system uses currently; null if the image can't be loaded
      • isDisposed

        public static boolean isDisposed()
        Checks if the turtle frame was disposed or released.
      • dispose

        public void dispose()
        Disposes the TurtleFrame.
      • startPath

        public Turtle startPath()
        Starts recording the path vertexes where the turtle moves. The path is used to draw a filled region with fillPath().
        If wrapping is enabled, the path vertexes correspond to the non-wrapped turtle positions.
        Returns:
        the turtle reference to allow chaining
      • fillPath

        public Turtle fillPath()
        Closes the path (line from current position to where the turtle path starts) and fills the polygon with the current fill color. If no path was started or the path is already closed, nothing happens.
        Returns:
        the turtle reference to allow chaining
      • pushState

        public Turtle pushState()
        Saves the current turtle state in a turtle state buffer. The buffer is stack oriented, e.g. it is a FIFO-buffer (First In-First Out).
        The following turtle properties are saved:
        - current position
        - current color
        - current heading

        The states can be restored by calling popState().
        Returns:
        the turtle reference to allow chaining
      • popState

        public Turtle popState()
        Retrieves the last state from the turtle state buffer and sets the turtle properties accordingly. The state is then removed from the state buffer.
        If the turtle state buffer is empty, nothing happens.
        Returns:
        the turtle reference to allow chaining
      • clearStates

        public Turtle clearStates()
        Empties the state buffer. The current turtle state remains unchanged.
        Returns:
        the turtle reference to allow chaining
      • viewingSetPos

        public Turtle viewingSetPos(double x,
                           double y)
        Puts the turtle to a new relative position without drawing a trace. For the given x, y coordinates a coordinate system relative to the current position and heading (viewing direction) is used (zero at current position, y-axis in viewing direction, x-axis perpendicular to the right).
        Parameters:
        x - the relative x coordinate
        y - the relative y coordinate
        Returns:
        the turtle reference to allow chaining
      • viewingMoveTo

        public Turtle viewingMoveTo(double x,
                           double y)
        Moves the turtle to the new relative position. First the turtle turns to the new heading, then it moves forward. For the given x, y coordinates a coordinate system relative to the current position and heading (viewing direction) is used (zero at current position, y-axis in viewing direction, x-axis perpendicular to the right).
        Parameters:
        x - the relative x coordinate
        y - the relative y coordinate
        Returns:
        the turtle reference to allow chaining