========================================

:mod:`turtle` --- Turtle graphics for Tk

========================================

.. module:: turtle

   :synopsis: Turtle graphics for Tk

.. sectionauthor:: Gregor Lingl <gregor.lingl@aon.at>

Introduction

============

Turtle graphics is a popular way for introducing programming to kids.  It was

part of the original Logo programming language developed by Wally Feurzig and

Seymour Papert in 1966.

Imagine a robotic turtle starting at (0, 0) in the x-y plane.  Give it the

command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the

direction it is facing, drawing a line as it moves.  Give it the command

``turtle.left(25)``, and it rotates in-place 25 degrees clockwise.

By combining together these and similar commands, intricate shapes and pictures

can easily be drawn.

The :mod:`turtle` module is an extended reimplementation of the same-named

module from the Python standard distribution up to version Python 2.5.

It tries to keep the merits of the old turtle module and to be (nearly) 100%

compatible with it.  This means in the first place to enable the learning

programmer to use all the commands, classes and methods interactively when using

the module from within IDLE run with the ``-n`` switch.

The turtle module provides turtle graphics primitives, in both object-oriented

and procedure-oriented ways.  Because it uses :mod:`Tkinter` for the underlying

graphics, it needs a version of python installed with Tk support.

The object-oriented interface uses essentially two+two classes:

1. The :class:`TurtleScreen` class defines graphics windows as a playground for

   the drawing turtles.  Its constructor needs a :class:`Tkinter.Canvas` or a

   :class:`ScrolledCanvas` as argument.  It should be used when :mod:`turtle` is

   used as part of some application.

   The function :func:`Screen` returns a singleton object of a

   :class:`TurtleScreen` subclass. This function should be used when

   :mod:`turtle` is used as a standalone tool for doing graphics.

   As a singleton object, inheriting from its class is not possible.

   All methods of TurtleScreen/Screen also exist as functions, i.e. as part of

   the procedure-oriented interface.

2. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw

   on a :class:`TurtleScreen`.  Its constructor needs a Canvas, ScrolledCanvas

   or TurtleScreen as argument, so the RawTurtle objects know where to draw.

   Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`),

   which draws on "the" :class:`Screen` - instance which is automatically

   created, if not already present.

   All methods of RawTurtle/Turtle also exist as functions, i.e. part of the

   procedure-oriented interface.

The procedural interface provides functions which are derived from the methods

of the classes :class:`Screen` and :class:`Turtle`.  They have the same names as

the corresponding methods.  A screen object is automativally created whenever a

function derived from a Screen method is called.  An (unnamed) turtle object is

automatically created whenever any of the functions derived from a Turtle method

is called.

To use multiple turtles an a screen one has to use the object-oriented interface.

.. note::

   In the following documentation the argument list for functions is given.

   Methods, of course, have the additional first argument *self* which is

   omitted here.

Overview over available Turtle and Screen methods

=================================================

Turtle methods

--------------

Turtle motion

   Move and draw

      | :func:`forward` | :func:`fd`

      | :func:`backward` | :func:`bk` | :func:`back`

      | :func:`right` | :func:`rt`

      | :func:`left` | :func:`lt`

      | :func:`goto` | :func:`setpos` | :func:`setposition`

      | :func:`setx`

      | :func:`sety`

      | :func:`setheading` | :func:`seth`

      | :func:`home`

      | :func:`circle`

      | :func:`dot`

      | :func:`stamp`

      | :func:`clearstamp`

      | :func:`clearstamps`

      | :func:`undo`

      | :func:`speed`

   Tell Turtle's state

      | :func:`position` | :func:`pos`

      | :func:`towards`

      | :func:`xcor`

      | :func:`ycor`

      | :func:`heading`

      | :func:`distance`

   Setting and measurement

      | :func:`degrees`

      | :func:`radians`

Pen control

   Drawing state

      | :func:`pendown` | :func:`pd` | :func:`down`

      | :func:`penup` | :func:`pu` | :func:`up`

      | :func:`pensize` | :func:`width`

      | :func:`pen`

      | :func:`isdown`

   Color control

      | :func:`color`

      | :func:`pencolor`

      | :func:`fillcolor`

   Filling

      | :func:`fill`

      | :func:`begin_fill`

      | :func:`end_fill`

   More drawing control

      | :func:`reset`

      | :func:`clear`

      | :func:`write`

Turtle state

   Visibility

      | :func:`showturtle` | :func:`st`

      | :func:`hideturtle` | :func:`ht`

      | :func:`isvisible`

   Appearance

      | :func:`shape`

      | :func:`resizemode`

      | :func:`shapesize` | :func:`turtlesize`

      | :func:`settiltangle`

      | :func:`tiltangle`

      | :func:`tilt`

Using events

   | :func:`onclick`

   | :func:`onrelease`

   | :func:`ondrag`

Special Turtle methods

   | :func:`begin_poly`

   | :func:`end_poly`

   | :func:`get_poly`

   | :func:`clone`

   | :func:`getturtle` | :func:`getpen`

   | :func:`getscreen`

   | :func:`setundobuffer`

   | :func:`undobufferentries`

   | :func:`tracer`

   | :func:`window_width`

   | :func:`window_height`

Methods of TurtleScreen/Screen

------------------------------

Window control

   | :func:`bgcolor`

   | :func:`bgpic`

   | :func:`clear` | :func:`clearscreen`

   | :func:`reset` | :func:`resetscreen`

   | :func:`screensize`

   | :func:`setworldcoordinates`

Animation control

   | :func:`delay`

   | :func:`tracer`

   | :func:`update`

Using screen events

   | :func:`listen`

   | :func:`onkey`

   | :func:`onclick` | :func:`onscreenclick`

   | :func:`ontimer`

Settings and special methods

   | :func:`mode`

   | :func:`colormode`

   | :func:`getcanvas`

   | :func:`getshapes`

   | :func:`register_shape` | :func:`addshape`

   | :func:`turtles`

   | :func:`window_height`

   | :func:`window_width`

Methods specific to Screen

   | :func:`bye`

   | :func:`exitonclick`

   | :func:`setup`

   | :func:`title`

Methods of RawTurtle/Turtle and corresponding functions

=======================================================

Most of the examples in this section refer to a Turtle instance called

``turtle``.

Turtle motion

-------------

.. function:: forward(distance)

              fd(distance)

   :param distance: a number (integer or float)

   Move the turtle forward by the specified *distance*, in the direction the

   turtle is headed.

   >>> turtle.position()

   (0.00, 0.00)

   >>> turtle.forward(25)

   >>> turtle.position()

   (25.00,0.00)

   >>> turtle.forward(-75)

   >>> turtle.position()

   (-50.00,0.00)

.. function:: back(distance)

              bk(distance)

              backward(distance)

   :param distance: a number

   Move the turtle backward by *distance*, opposite to the direction the

   turtle is headed.  Do not change the turtle's heading.

   >>> turtle.position()

   (0.00, 0.00)

   >>> turtle.backward(30)

   >>> turtle.position()

   (-30.00, 0.00)

.. function:: right(angle)

              rt(angle)

   :param angle: a number (integer or float)

   Turn turtle right by *angle* units.  (Units are by default degrees, but

   can be set via the :func:`degrees` and :func:`radians` functions.)  Angle

   orientation depends on the turtle mode, see :func:`mode`.

   >>> turtle.heading()

   22.0

   >>> turtle.right(45)

   >>> turtle.heading()

   337.0

.. function:: left(angle)

              lt(angle)

   :param angle: a number (integer or float)

   Turn turtle left by *angle* units.  (Units are by default degrees, but

   can be set via the :func:`degrees` and :func:`radians` functions.)  Angle

   orientation depends on the turtle mode, see :func:`mode`.

   >>> turtle.heading()

   22.0

   >>> turtle.left(45)

   >>> turtle.heading()

   67.0

.. function:: goto(x, y=None)

              setpos(x, y=None)

              setposition(x, y=None)

    :param x: a number or a pair/vector of numbers

    :param y: a number or ``None``

    If *y* is ``None``, *x* must be a pair of coordinates or a :class:`Vec2D`

    (e.g. as returned by :func:`pos`).

    Move turtle to an absolute position.  If the pen is down, draw line.  Do

    not change the turtle's orientation.

    >>> tp = turtle.pos()

    >>> tp

    (0.00, 0.00)

    >>> turtle.setpos(60,30)

    >>> turtle.pos()

    (60.00,30.00)

    >>> turtle.setpos((20,80))

    >>> turtle.pos()

    (20.00,80.00)

    >>> turtle.setpos(tp)

    >>> turtle.pos()

    (0.00,0.00)

.. function:: setx(x)

   :param x: a number (integer or float)

   Set the turtle's first coordinate to *x*, leave second coordinate

   unchanged.

   >>> turtle.position()

   (0.00, 240.00)

   >>> turtle.setx(10)

   >>> turtle.position()

   (10.00, 240.00)

.. function:: sety(y)

   :param y: a number (integer or float)

   Set the turtle's first coordinate to *y*, leave second coordinate

   unchanged.

   >>> turtle.position()

   (0.00, 40.00)

   >>> turtle.sety(-10)

   >>> turtle.position()

   (0.00, -10.00)

.. function:: setheading(to_angle)

              seth(to_angle)

   :param to_angle: a number (integer or float)

   Set the orientation of the turtle to *to_angle*.  Here are some common

   directions in degrees:

   =================== ====================

    standard mode           logo mode

   =================== ====================

      0 - east                0 - north

     90 - north              90 - east

    180 - west              180 - south

    270 - south             270 - west

   =================== ====================

   >>> turtle.setheading(90)

   >>> turtle.heading()

   90

.. function:: home()

   Move turtle to the origin -- coordinates (0,0) -- and set its heading to

   its start-orientation (which depends on the mode, see :func:`mode`).

.. function:: circle(radius, extent=None, steps=None)

   :param radius: a number

   :param extent: a number (or ``None``)

   :param steps: an integer (or ``None``)

   Draw a circle with given *radius*.  The center is *radius* units left of

   the turtle; *extent* -- an angle -- determines which part of the circle

   is drawn.  If *extent* is not given, draw the entire circle.  If *extent*

   is not a full circle, one endpoint of the arc is the current pen

   position.  Draw the arc in counterclockwise direction if *radius* is

   positive, otherwise in clockwise direction.  Finally the direction of the

   turtle is changed by the amount of *extent*.

   As the circle is approximated by an inscribed regular polygon, *steps*

   determines the number of steps to use.  If not given, it will be

   calculated automatically.  May be used to draw regular polygons.

   >>> turtle.circle(50)

   >>> turtle.circle(120, 180)  # draw a semicircle

.. function:: dot(size=None, *color)

   :param size: an integer >= 1 (if given)

   :param color: a colorstring or a numeric color tuple

   Draw a circular dot with diameter *size*, using *color*.  If *size* is

   not given, the maximum of pensize+4 and 2*pensize is used.

   >>> turtle.dot()

   >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)

.. function:: stamp()

   Stamp a copy of the turtle shape onto the canvas at the current turtle

   position.  Return a stamp_id for that stamp, which can be used to delete

   it by calling ``clearstamp(stamp_id)``.

   >>> turtle.color("blue")

   >>> turtle.stamp()

   13

   >>> turtle.fd(50)

.. function:: clearstamp(stampid)

   :param stampid: an integer, must be return value of previous

                   :func:`stamp` call

   Delete stamp with given *stampid*.

   >>> turtle.color("blue")

   >>> astamp = turtle.stamp()

   >>> turtle.fd(50)

   >>> turtle.clearstamp(astamp)

.. function:: clearstamps(n=None)

   :param n: an integer (or ``None``)

   Delete all or first/last *n* of turtle's stamps.  If *n* is None, delete

   all stamps, if *n* > 0 delete first *n* stamps, else if *n* < 0 delete

   last *n* stamps.

   >>> for i in range(8):

   ...     turtle.stamp(); turtle.fd(30)

   >>> turtle.clearstamps(2)

   >>> turtle.clearstamps(-2)

   >>> turtle.clearstamps()

.. function:: undo()

   Undo (repeatedly) the last turtle action(s).  Number of available

   undo actions is determined by the size of the undobuffer.

   >>> for i in range(4):

   ...     turtle.fd(50); turtle.lt(80)

   ...

   >>> for i in range(8):

   ...     turtle.undo()

.. function:: speed(speed=None)

   :param speed: an integer in the range 0..10 or a speedstring (see below)

   Set the turtle's speed to an integer value in the range 0..10.  If no

   argument is given, return current speed.

   If input is a number greater than 10 or smaller than 0.5, speed is set

   to 0.  Speedstrings are mapped to speedvalues as follows:

   * "fastest":  0

   * "fast":  10

   * "normal":  6

   * "slow":  3

   * "slowest":  1

   Speeds from 1 to 10 enforce increasingly faster animation of line drawing

   and turtle turning.

   Attention: *speed* = 0 means that *no* animation takes

   place. forward/back makes turtle jump and likewise left/right make the

   turtle turn instantly.

   >>> turtle.speed(3)

Tell Turtle's state

-------------------

.. function:: position()

              pos()

   Return the turtle's current location (x,y) (as a :class:`Vec2D` vector).

   >>> turtle.pos()

   (0.00, 240.00)

.. function:: towards(x, y=None)

   :param x: a number or a pair/vector of numbers or a turtle instance

   :param y: a number if *x* is a number, else ``None``

   Return the angle between the line from turtle position to position specified

   by (x,y), the vector or the other turtle.  This depends on the turtle's start

   orientation which depends on the mode - "standard"/"world" or "logo").

   >>> turtle.pos()

   (10.00, 10.00)

   >>> turtle.towards(0,0)

   225.0

.. function:: xcor()

   Return the turtle's x coordinate.

   >>> reset()

   >>> turtle.left(60)

   >>> turtle.forward(100)

   >>> print turtle.xcor()

   50.0

.. function:: ycor()

   Return the turtle's y coordinate.

   >>> reset()

   >>> turtle.left(60)

   >>> turtle.forward(100)

   >>> print turtle.ycor()

   86.6025403784

.. function:: heading()