20.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.

setup( **kwargs)

Sets the size and position of the main window. Keywords are:

• width: either a size in pixels or a fraction of the screen. The default is 50% of the screen.
• height: either a size in pixels or a fraction of the screen. The default is 50% of the screen.
• startx: starting position in pixels from the left edge of the screen. None is the default value and centers the window horizontally on screen.
• starty: starting position in pixels from the top edge of the screen. None is the default value and centers the window vertically on screen.

Examples:

# Uses default geometry: 50% x 50% of screen, centered.
setup() 
# Sets window to 200x200 pixels, in upper left of screen
setup (width=200, height=200, startx=0, starty=0)
# Sets window to 75% of screen by 50% of screen, and centers it.
setup(width=.75, height=0.5, startx=None, starty=None)

title( title_str)

Set the window's title to title.

done( )

Enters the Tk main loop. The window will continue to be displayed until the user closes it or the process is killed.

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.

speed( speed)

Set the speed of the turtle. Valid values for the parameter speed are 'fastest' (no delay), 'fast', (delay 5ms), 'normal' (delay 10ms), 'slow' (delay 15ms), and 'slowest' (delay 20ms). New in version 2.5.

delay( delay)

Set the speed of the turtle to delay, which is given in ms. New in version 2.5.

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.

begin_fill( )

Switch turtle into filling mode; Must eventually be followed by a corresponding end_fill() call. Otherwise it will be ignored. New in version 2.5.

end_fill( )

End filling mode, and fill the shape; equivalent to fill(0). New in version 2.5.

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.

towards( x, y)

Return the angle of the line from the turtle's position to the point x, y. The co-ordinates may be specified either as two separate arguments, as a 2-tuple, or as another pen object. New in version 2.5.

heading( )

Return the current orientation of the turtle. New in version 2.3.

setheading( angle)

Set the orientation of the turtle to angle. New in version 2.3.

position( )

Return the current location of the turtle as an (x,y) pair. New in version 2.3.

setx( x)

Set the x coordinate of the turtle to x. New in version 2.3.

sety( y)

Set the y coordinate of the turtle to y. New in version 2.3.

window_width( )

Return the width of the canvas window. New in version 2.3.

window_height( )

Return the height of the canvas window. New in version 2.3.

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 Turtle( )

Define a pen. This is essentially a synonym for Pen(); Turtle is an empty subclass of Pen.

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.

---

See About this document... for information on suggesting changes.