24.5. turtle — Turtle graphics for Tk

24.5.1. 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. After an import turtle, 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.right(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 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 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 TurtleScreen class defines graphics windows as a playground for the drawing turtles. Its constructor needs a Tkinter.Canvas or a ScrolledCanvas as argument. It should be used when turtle is used as part of some application.

   The function Screen() returns a singleton object of a TurtleScreen subclass. This function should be used when 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. RawTurtle (alias: RawPen) defines Turtle objects which draw on a 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 Turtle (alias: Pen), which draws on “the” 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 Screen and Turtle. They have the same names as the corresponding methods. A screen object is automatically 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.

24.5.2. Overview over available Turtle and Screen methods

24.5.2.1. Turtle methods

Turtle motion

Move and draw

forward() | fd()

backward() | bk() | back()

right() | rt()

left() | lt()

goto() | setpos() | setposition()

setx()

sety()

setheading() | seth()

home()

circle()

dot()

stamp()

clearstamp()

clearstamps()

undo()

speed()

Tell Turtle’s state

position() | pos()

towards()

xcor()

ycor()

heading()

distance()

Setting and measurement

degrees()

radians()

Pen control

Drawing state

pendown() | pd() | down()

penup() | pu() | up()

pensize() | width()

pen()

isdown()

Color control

color()

pencolor()

fillcolor()

Filling

fill()

begin_fill()

end_fill()

More drawing control

reset()

clear()

write()

Turtle state

Visibility

showturtle() | st()

hideturtle() | ht()

isvisible()

Appearance

shape()

resizemode()

shapesize() | turtlesize()

settiltangle()

tiltangle()

tilt()

Using events

onclick()

onrelease()

ondrag()

mainloop() | done()

Special Turtle methods

begin_poly()

end_poly()

get_poly()

clone()

getturtle() | getpen()

getscreen()

setundobuffer()

undobufferentries()

tracer()

window_width()

window_height()

24.5.2.2. Methods of TurtleScreen/Screen

Window control

bgcolor()

bgpic()

clear() | clearscreen()

reset() | resetscreen()

screensize()

setworldcoordinates()

Animation control

delay()

tracer()

update()

Using screen events

listen()

onkey()

onclick() | onscreenclick()

ontimer()

Settings and special methods

mode()

colormode()

getcanvas()

getshapes()

register_shape() | addshape()

turtles()

window_height()

window_width()

Methods specific to Screen

bye()

exitonclick()

setup()

title()

24.5.3. Methods of RawTurtle/Turtle and corresponding functions

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

24.5.3.1. Turtle motion

turtle.forward(distance)

turtle.fd(distance)

Parameters

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