16.4 turtle -- Turtle graphics for Tk
Description: turtle -- Turtle graphics for Tk
Keywords: lib

# 16.4 `turtle` -- Turtle graphics for Tk

Availability: Tk.

The `turtle` module provides turtle graphics primitives, in both an object-oriented and procedure-oriented ways. Because it uses `Tkinter` for the underlying graphics, it needs a version of python installed with Tk support.

The procedural interface uses a pen and a canvas which are automagically created when any of the functions are called.

The `turtle` module defines the following functions:

`degrees`( | )

  Set angle measurement units to degrees.

`radians`( | )

  Set angle measurement units to radians.

`reset`( | )

  Clear the screen, re-center the pen, and set variables to the default values.

`clear`( | )

  Clear the screen.

`tracer`( | flag)

  Set tracing on/off (according to whether flag is true or not). Tracing means line are drawn more slowly, with an animation of an arrow along the line.

`forward`( | distance)

  Go forward distance steps.

`backward`( | distance)

  Go backward distance steps.

`left`( | angle)

  Turn left angle units. Units are by default degrees, but can be set via the `degrees()` and `radians()` functions.

`right`( | angle)

  Turn right angle units. Units are by default degrees, but can be set via the `degrees()` and `radians()` functions.

`up`( | )

  Move the pen up -- stop drawing.

`down`( | )

  Move the pen down -- draw when moving.

`width`( | width)

  Set the line width to width.

`color`( | s)

`color`( | (r, g, b))

`color`( | r, g, b)

  Set the pen color. In the first form, the color is specified as a Tk color specification as a string. The second form specifies the color as a tuple of the RGB values, each in the range [0..1]. For the third form, the color is specified giving the RGB values as three separate parameters (each in the range [0..1]).

`write`( | text[, move])

  Write text at the current pen position. If move is true, the pen is moved to the bottom-right corner of the text. By default, move is false.

`fill`( | flag)

  The complete specifications are rather complex, but the recommended usage is: call `fill(1)` before drawing a path you want to fill, and call `fill(0)` when you finish to draw the path.

`circle`( | radius[, extent])

  Draw a circle with radius radius whose center-point is radius units left of the turtle. extent determines which part of a circle is drawn: if not given it defaults to a full circle.

  If extent is not a full circle, one endpoint of the arc is the current pen position. The arc is drawn in a counter clockwise direction if radius is positive, otherwise in a clockwise direction. In the process, the direction of the turtle is changed by the amount of the extent.

`goto`( | x, y)

`goto`( | (x, y))

  Go to co-ordinates x, y. The co-ordinates may be specified either as two separate arguments or as a 2-tuple.

This module also does `from math import *`, so see the documentation for the `math` module for additional constants and functions useful for turtle graphics.

`demo`( | )

  Exercise the module a bit.

exception `Error`
  Exception raised on any error caught by this module.

For examples, see the code of the `demo()` function.

This module defines the following classes:

class `Pen`( | )

  Define a pen. All above functions can be called as a methods on the given pen. The constructor automatically creates a canvas do be drawn on.

class `RawPen`( | canvas)

  Define a pen which draws on a canvas canvas. This is useful if you want to use the module to create graphics in a ``real'' program.