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

filling()

begin_fill()

end_fill()

More drawing control

reset()

clear()

write()

Turtle state

Visibility

showturtle() |st()

hideturtle() |ht()

isvisible()

Appearance

shape()

resizemode()

shapesize() |turtlesize()

shearfactor()

settiltangle()

tiltangle()

tilt()

shapetransform()

get_shapepoly()

Using events

onclick()

onrelease()

ondrag()

Special Turtle methods

begin_poly()

end_poly()

get_poly()

clone()

getturtle() |getpen()

getscreen()

setundobuffer()

undobufferentries()

Methods of TurtleScreen/Screen¶

Window control

bgcolor()

bgpic()

clear() |clearscreen()

reset() |resetscreen()

screensize()

setworldcoordinates()

Animation control

delay()

tracer()

update()

Using screen events

listen()

onkey() |onkeyrelease()

onkeypress()

onclick() |onscreenclick()

ontimer()

mainloop() |done()

Settings and special methods

mode()

colormode()

getcanvas()

getshapes()

register_shape() |addshape()

turtles()

window_height()

window_width()

Input methods

textinput()

numinput()

Methods specific to Screen

bye()

exitonclick()

setup()

title()

Turtle motion¶

turtle.forward(distance)¶

turtle.fd(distance)¶

Parameters

distance – a number (integer or float)

Move the turtle forward by the specifieddistance, in the direction theturtle 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)

turtle.back(distance)¶

turtle.bk(distance)¶

turtle.backward(distance)¶

Parameters

distance – a number

Move the turtle backward bydistance, opposite to the direction theturtle is headed. Do not change the turtle’s heading.

>>>turtle.position()(0.00,0.00)>>>turtle.backward(30)>>>turtle.position()(-30.00,0.00)

turtle.right(angle)¶

turtle.rt(angle)¶

Parameters

angle – a number (integer or float)

Turn turtle right byangle units. (Units are by default degrees, butcan be set via thedegrees() andradians() functions.) Angleorientation depends on the turtle mode, seemode().

>>>turtle.heading()22.0>>>turtle.right(45)>>>turtle.heading()337.0

turtle.left(angle)¶

turtle.lt(angle)¶

Parameters

angle – a number (integer or float)

Turn turtle left byangle units. (Units are by default degrees, butcan be set via thedegrees() andradians() functions.) Angleorientation depends on the turtle mode, seemode().

>>>turtle.heading()22.0>>>turtle.left(45)>>>turtle.heading()67.0

turtle.goto(x,y=None)¶

turtle.setpos(x,y=None)¶

turtle.setposition(x,y=None)¶

Parameters

• x – a number or a pair/vector of numbers

• y – a number orNone

Ify isNone,x must be a pair of coordinates or aVec2D(e.g. as returned bypos()).

Move turtle to an absolute position. If the pen is down, draw line. Donot 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)

turtle.setx(x)¶

Parameters

x – a number (integer or float)

Set the turtle’s first coordinate tox, leave second coordinateunchanged.

>>>turtle.position()(0.00,240.00)>>>turtle.setx(10)>>>turtle.position()(10.00,240.00)

turtle.sety(y)¶

Parameters

y – a number (integer or float)

Set the turtle’s second coordinate toy, leave first coordinate unchanged.

>>>turtle.position()(0.00,40.00)>>>turtle.sety(-10)>>>turtle.position()(0.00,-10.00)

turtle.setheading(to_angle)¶

turtle.seth(to_angle)¶

Parameters

to_angle – a number (integer or float)

Set the orientation of the turtle toto_angle. Here are some commondirections 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.0

turtle.home()¶

Move turtle to the origin – coordinates (0,0) – and set its heading toits start-orientation (which depends on the mode, seemode()).

>>>turtle.heading()90.0>>>turtle.position()(0.00,-10.00)>>>turtle.home()>>>turtle.position()(0.00,0.00)>>>turtle.heading()0.0

turtle.circle(radius,extent=None,steps=None)¶

Parameters

• radius – a number

• extent – a number (orNone)

• steps – an integer (orNone)

Draw a circle with givenradius. The center isradius units left ofthe turtle;extent – an angle – determines which part of the circleis drawn. Ifextent is not given, draw the entire circle. Ifextentis not a full circle, one endpoint of the arc is the current penposition. Draw the arc in counterclockwise direction ifradius ispositive, otherwise in clockwise direction. Finally the direction of theturtle is changed by the amount ofextent.

As the circle is approximated by an inscribed regular polygon,stepsdetermines the number of steps to use. If not given, it will becalculated automatically. May be used to draw regular polygons.

>>>turtle.home()>>>turtle.position()(0.00,0.00)>>>turtle.heading()0.0>>>turtle.circle(50)>>>turtle.position()(-0.00,0.00)>>>turtle.heading()0.0>>>turtle.circle(120,180)# draw a semicircle>>>turtle.position()(0.00,240.00)>>>turtle.heading()180.0

turtle.dot(size=None,*color)¶

Parameters

• size – an integer >= 1 (if given)

• color – a colorstring or a numeric color tuple

Draw a circular dot with diametersize, usingcolor. Ifsize isnot given, the maximum of pensize+4 and 2*pensize is used.

>>>turtle.home()>>>turtle.dot()>>>turtle.fd(50);turtle.dot(20,"blue");turtle.fd(50)>>>turtle.position()(100.00,-0.00)>>>turtle.heading()0.0

turtle.stamp()¶

Stamp a copy of the turtle shape onto the canvas at the current turtleposition. Return a stamp_id for that stamp, which can be used to deleteit by callingclearstamp(stamp_id).

>>>turtle.color("blue")>>>turtle.stamp()11>>>turtle.fd(50)

turtle.clearstamp(stampid)¶

Parameters

stampid – an integer, must be return value of previousstamp() call

Delete stamp with givenstampid.

>>>turtle.position()(150.00,-0.00)>>>turtle.color("blue")>>>astamp=turtle.stamp()>>>turtle.fd(50)>>>turtle.position()(200.00,-0.00)>>>turtle.clearstamp(astamp)>>>turtle.position()(200.00,-0.00)

turtle.clearstamps(n=None)¶

Parameters

n – an integer (orNone)

Delete all or first/lastn of turtle’s stamps. Ifn isNone, deleteall stamps, ifn > 0 delete firstn stamps, else ifn < 0 deletelastn stamps.

>>>foriinrange(8):...turtle.stamp();turtle.fd(30)1314151617181920>>>turtle.clearstamps(2)>>>turtle.clearstamps(-2)>>>turtle.clearstamps()

turtle.undo()¶

Undo (repeatedly) the last turtle action(s). Number of availableundo actions is determined by the size of the undobuffer.

>>>foriinrange(4):...turtle.fd(50);turtle.lt(80)...>>>foriinrange(8):...turtle.undo()

turtle.speed(speed=None)¶

Parameters

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 noargument is given, return current speed.

If input is a number greater than 10 or smaller than 0.5, speed is setto 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 drawingand turtle turning.

Attention:speed = 0 means thatno animation takesplace. forward/back makes turtle jump and likewise left/right make theturtle turn instantly.

>>>turtle.speed()3>>>turtle.speed('normal')>>>turtle.speed()6>>>turtle.speed(9)>>>turtle.speed()9

Tell Turtle’s state¶

turtle.position()¶

turtle.pos()¶

Return the turtle’s current location (x,y) (as aVec2D vector).

>>>turtle.pos()(440.00,-0.00)

turtle.towards(x,y=None)¶

Parameters

• x – a number or a pair/vector of numbers or a turtle instance

• y – a number ifx is a number, elseNone

Return the angle between the line from turtle position to position specifiedby (x,y), the vector or the other turtle. This depends on the turtle’s startorientation which depends on the mode - “standard”/”world” or “logo”.

>>>turtle.goto(10,10)>>>turtle.towards(0,0)225.0

turtle.xcor()¶

Return the turtle’s x coordinate.

>>>turtle.home()>>>turtle.left(50)>>>turtle.forward(100)>>>turtle.pos()(64.28,76.60)>>>print(round(turtle.xcor(),5))64.27876

turtle.ycor()¶

Return the turtle’s y coordinate.

>>>turtle.home()>>>turtle.left(60)>>>turtle.forward(100)>>>print(turtle.pos())(50.00,86.60)>>>print(round(turtle.ycor(),5))86.60254

turtle.heading()¶

Return the turtle’s current heading (value depends on the turtle mode, seemode()).

>>>turtle.home()>>>turtle.left(67)>>>turtle.heading()67.0

turtle.distance(x,y=None)¶

Parameters

• x – a number or a pair/vector of numbers or a turtle instance

• y – a number ifx is a number, elseNone

Return the distance from the turtle to (x,y), the given vector, or the givenother turtle, in turtle step units.

>>>turtle.home()>>>turtle.distance(30,40)50.0>>>turtle.distance((30,40))50.0>>>joe=Turtle()>>>joe.forward(77)>>>turtle.distance(joe)77.0

Settings for measurement¶

turtle.degrees(fullcircle=360.0)¶

Parameters

fullcircle – a number

Set angle measurement units, i.e. set number of “degrees” for a full circle.Default value is 360 degrees.

>>>turtle.home()>>>turtle.left(90)>>>turtle.heading()90.0Change angle measurement unit to grad (also known as gon,grade, or gradian and equals 1/100-th of the right angle.)>>>turtle.degrees(400.0)>>>turtle.heading()100.0>>>turtle.degrees(360)>>>turtle.heading()90.0

turtle.radians()¶

Set the angle measurement units to radians. Equivalent todegrees(2*math.pi).

>>>turtle.home()>>>turtle.left(90)>>>turtle.heading()90.0>>>turtle.radians()>>>turtle.heading()1.5707963267948966

Pen control¶

Turtle state¶

Using events¶

turtle.onclick(fun,btn=1,add=None)

Parameters

• fun – a function with two arguments which will be called with thecoordinates of the clicked point on the canvas

• btn – number of the mouse-button, defaults to 1 (left mouse button)

• add –True orFalse – ifTrue, a new binding will beadded, otherwise it will replace a former binding

Bindfun to mouse-click events on this turtle. Iffun isNone,existing bindings are removed. Example for the anonymous turtle, i.e. theprocedural way:

>>>defturn(x,y):...left(180)...>>>onclick(turn)# Now clicking into the turtle will turn it.>>>onclick(None)# event-binding will be removed

turtle.onrelease(fun,btn=1,add=None)¶

Parameters

• fun – a function with two arguments which will be called with thecoordinates of the clicked point on the canvas

• btn – number of the mouse-button, defaults to 1 (left mouse button)

• add –True orFalse – ifTrue, a new binding will beadded, otherwise it will replace a former binding

Bindfun to mouse-button-release events on this turtle. Iffun isNone, existing bindings are removed.

>>>classMyTurtle(Turtle):...defglow(self,x,y):...self.fillcolor("red")...defunglow(self,x,y):...self.fillcolor("")...>>>turtle=MyTurtle()>>>turtle.onclick(turtle.glow)# clicking on turtle turns fillcolor red,>>>turtle.onrelease(turtle.unglow)# releasing turns it to transparent.

turtle.ondrag(fun,btn=1,add=None)¶

Parameters

• fun – a function with two arguments which will be called with thecoordinates of the clicked point on the canvas

• btn – number of the mouse-button, defaults to 1 (left mouse button)

• add –True orFalse – ifTrue, a new binding will beadded, otherwise it will replace a former binding

Bindfun to mouse-move events on this turtle. Iffun isNone,existing bindings are removed.

Remark: Every sequence of mouse-move-events on a turtle is preceded by amouse-click event on that turtle.

>>>turtle.ondrag(turtle.goto)

Subsequently, clicking and dragging the Turtle will move it acrossthe screen thereby producing handdrawings (if pen is down).

Special Turtle methods¶

turtle.begin_poly()¶

Start recording the vertices of a polygon. Current turtle position is firstvertex of polygon.

turtle.end_poly()¶

Stop recording the vertices of a polygon. Current turtle position is lastvertex of polygon. This will be connected with the first vertex.

turtle.get_poly()¶

Return the last recorded polygon.

>>>turtle.home()>>>turtle.begin_poly()>>>turtle.fd(100)>>>turtle.left(20)>>>turtle.fd(30)>>>turtle.left(60)>>>turtle.fd(50)>>>turtle.end_poly()>>>p=turtle.get_poly()>>>register_shape("myFavouriteShape",p)

turtle.clone()¶

Create and return a clone of the turtle with same position, heading andturtle properties.

>>>mick=Turtle()>>>joe=mick.clone()

turtle.getturtle()¶

turtle.getpen()¶

Return the Turtle object itself. Only reasonable use: as a function toreturn the “anonymous turtle”:

>>>pet=getturtle()>>>pet.fd(50)>>>pet<turtle.Turtle object at 0x...>

turtle.getscreen()¶

Return theTurtleScreen object the turtle is drawing on.TurtleScreen methods can then be called for that object.

>>>ts=turtle.getscreen()>>>ts<turtle._Screen object at 0x...>>>>ts.bgcolor("pink")

turtle.setundobuffer(size)¶

Parameters

size – an integer orNone

Set or disable undobuffer. Ifsize is an integer, an empty undobuffer ofgiven size is installed.size gives the maximum number of turtle actionsthat can be undone by theundo() method/function. Ifsize isNone, the undobuffer is disabled.

>>>turtle.setundobuffer(42)

turtle.undobufferentries()¶

Return number of entries in the undobuffer.

>>>whileundobufferentries():...undo()

Compound shapes¶

To use compound turtle shapes, which consist of several polygons of differentcolor, you must use the helper classShape explicitly as describedbelow:

1. Create an empty Shape object of type “compound”.

2. Add as many components to this object as desired, using theaddcomponent() method.

   For example:

   >>>s=Shape("compound")>>>poly1=((0,0),(10,-5),(0,10),(-10,-5))>>>s.addcomponent(poly1,"red","blue")>>>poly2=((0,0),(10,-5),(-10,-5))>>>s.addcomponent(poly2,"blue","red")

3. Now add the Shape to the Screen’s shapelist and use it:

   >>>register_shape("myshape",s)>>>shape("myshape")

Window control¶

turtle.bgcolor(*args)¶

Parameters

args – a color string or three numbers in the range 0..colormode or a3-tuple of such numbers

Set or return background color of the TurtleScreen.

>>>screen.bgcolor("orange")>>>screen.bgcolor()'orange'>>>screen.bgcolor("#800080")>>>screen.bgcolor()(128.0, 0.0, 128.0)

turtle.bgpic(picname=None)¶

Parameters

picname – a string, name of a gif-file or"nopic", orNone

Set background image or return name of current backgroundimage. Ifpicnameis a filename, set the corresponding image as background. Ifpicname is"nopic", delete background image, if present. Ifpicname isNone,return the filename of the current backgroundimage.

>>>screen.bgpic()'nopic'>>>screen.bgpic("landscape.gif")>>>screen.bgpic()"landscape.gif"

turtle.clear()¶

turtle.clearscreen()¶

Delete all drawings and all turtles from the TurtleScreen. Reset the nowempty TurtleScreen to its initial state: white background, no backgroundimage, no event bindings and tracing on.

Note

This TurtleScreen method is available as a global function only under thenameclearscreen. The global functionclear is a different onederived from the Turtle methodclear.

turtle.reset()¶

turtle.resetscreen()¶

Reset all Turtles on the Screen to their initial state.

Note

This TurtleScreen method is available as a global function only under thenameresetscreen. The global functionreset is another onederived from the Turtle methodreset.

turtle.screensize(canvwidth=None,canvheight=None,bg=None)¶

Parameters

• canvwidth – positive integer, new width of canvas in pixels

• canvheight – positive integer, new height of canvas in pixels

• bg – colorstring or color-tuple, new background color

If no arguments are given, return current (canvaswidth, canvasheight). Elseresize the canvas the turtles are drawing on. Do not alter the drawingwindow. To observe hidden parts of the canvas, use the scrollbars. With thismethod, one can make visible those parts of a drawing which were outside thecanvas before.

>>>screen.screensize()(400, 300)>>>screen.screensize(2000,1500)>>>screen.screensize()(2000, 1500)

e.g. to search for an erroneously escaped turtle ;-)

turtle.setworldcoordinates(llx,lly,urx,ury)¶

Parameters

• llx – a number, x-coordinate of lower left corner of canvas

• lly – a number, y-coordinate of lower left corner of canvas

• urx – a number, x-coordinate of upper right corner of canvas

• ury – a number, y-coordinate of upper right corner of canvas

Set up user-defined coordinate system and switch to mode “world” ifnecessary. This performs ascreen.reset(). If mode “world” is alreadyactive, all drawings are redrawn according to the new coordinates.

ATTENTION: in user-defined coordinate systems angles may appeardistorted.

>>>screen.reset()>>>screen.setworldcoordinates(-50,-7.5,50,7.5)>>>for_inrange(72):...left(10)...>>>for_inrange(8):...left(45);fd(2)# a regular octagon

Animation control¶

turtle.delay(delay=None)¶

Parameters

delay – positive integer

Set or return the drawingdelay in milliseconds. (This is approximatelythe time interval between two consecutive canvas updates.) The longer thedrawing delay, the slower the animation.

Optional argument:

>>>screen.delay()10>>>screen.delay(5)>>>screen.delay()5

turtle.tracer(n=None,delay=None)¶

Parameters

• n – nonnegative integer

• delay – nonnegative integer

Turn turtle animation on/off and set delay for update drawings. Ifn is given, only each n-th regular screen update is reallyperformed. (Can be used to accelerate the drawing of complexgraphics.) When called without arguments, returns the currentlystored value of n. Second argument sets delay value (seedelay()).

>>>screen.tracer(8,25)>>>dist=2>>>foriinrange(200):...fd(dist)...rt(90)...dist+=2

turtle.update()¶

Perform a TurtleScreen update. To be used when tracer is turned off.

See also the RawTurtle/Turtle methodspeed().

Using screen events¶

turtle.listen(xdummy=None,ydummy=None)¶

Set focus on TurtleScreen (in order to collect key-events). Dummy argumentsare provided in order to be able to passlisten() to the onclick method.

turtle.onkey(fun,key)¶

turtle.onkeyrelease(fun,key)¶

Parameters

• fun – a function with no arguments orNone

• key – a string: key (e.g. “a”) or key-symbol (e.g. “space”)

Bindfun to key-release event of key. Iffun isNone, event bindingsare removed. Remark: in order to be able to register key-events, TurtleScreenmust have the focus. (See methodlisten().)

>>>deff():...fd(50)...lt(60)...>>>screen.onkey(f,"Up")>>>screen.listen()

turtle.onkeypress(fun,key=None)¶

Parameters

• fun – a function with no arguments orNone

• key – a string: key (e.g. “a”) or key-symbol (e.g. “space”)

Bindfun to key-press event of key if key is given,or to any key-press-event if no key is given.Remark: in order to be able to register key-events, TurtleScreenmust have focus. (See methodlisten().)

>>>deff():...fd(50)...>>>screen.onkey(f,"Up")>>>screen.listen()

turtle.onclick(fun,btn=1,add=None)¶

turtle.onscreenclick(fun,btn=1,add=None)¶

Parameters

• fun – a function with two arguments which will be called with thecoordinates of the clicked point on the canvas

• btn – number of the mouse-button, defaults to 1 (left mouse button)

• add –True orFalse – ifTrue, a new binding will beadded, otherwise it will replace a former binding

Bindfun to mouse-click events on this screen. Iffun isNone,existing bindings are removed.

Example for a TurtleScreen instance namedscreen and a Turtle instancenamedturtle:

>>>screen.onclick(turtle.goto)# Subsequently clicking into the TurtleScreen will>>># make the turtle move to the clicked point.>>>screen.onclick(None)# remove event binding again

Note

This TurtleScreen method is available as a global function only under thenameonscreenclick. The global functiononclick is another onederived from the Turtle methodonclick.

turtle.ontimer(fun,t=0)¶

Parameters

• fun – a function with no arguments

• t – a number >= 0

Install a timer that callsfun aftert milliseconds.

>>>running=True>>>deff():...ifrunning:...fd(50)...lt(60)...screen.ontimer(f,250)>>>f()### makes the turtle march around>>>running=False

turtle.mainloop()¶

turtle.done()¶

Starts event loop - calling Tkinter’s mainloop function.Must be the last statement in a turtle graphics program.Mustnot be used if a script is run from within IDLE in -n mode(No subprocess) - for interactive use of turtle graphics.

>>>screen.mainloop()

Input methods¶

turtle.textinput(title,prompt)¶

Parameters

• title – string

• prompt – string

Pop up a dialog window for input of a string. Parameter title isthe title of the dialog window, prompt is a text mostly describingwhat information to input.Return the string input. If the dialog is canceled, returnNone.

>>>screen.textinput("NIM","Name of first player:")

turtle.numinput(title,prompt,default=None,minval=None,maxval=None)¶

Parameters

• title – string

• prompt – string

• default – number (optional)

• minval – number (optional)

• maxval – number (optional)

Pop up a dialog window for input of a number. title is the title of thedialog window, prompt is a text mostly describing what numerical informationto input. default: default value, minval: minimum value for input,maxval: maximum value for inputThe number input must be in the range minval .. maxval if these aregiven. If not, a hint is issued and the dialog remains open forcorrection.Return the number input. If the dialog is canceled, returnNone.

>>>screen.numinput("Poker","Your stakes:",1000,minval=10,maxval=10000)

Settings and special methods¶

turtle.mode(mode=None)¶

Parameters

mode – one of the strings “standard”, “logo” or “world”

Set turtle mode (“standard”, “logo” or “world”) and perform reset. If modeis not given, current mode is returned.

Mode “standard” is compatible with oldturtle. Mode “logo” iscompatible with most Logo turtle graphics. Mode “world” uses user-defined“world coordinates”.Attention: in this mode angles appear distorted ifx/y unit-ratio doesn’t equal 1.

Mode	Initial turtle heading	positive angles
“standard”	to the right (east)	counterclockwise
“logo”	upward (north)	clockwise

>>>mode("logo")# resets turtle heading to north>>>mode()'logo'

turtle.colormode(cmode=None)¶

Parameters

cmode – one of the values 1.0 or 255

Return the colormode or set it to 1.0 or 255. Subsequentlyr,g,bvalues of color triples have to be in the range 0..cmode.

>>>screen.colormode(1)>>>turtle.pencolor(240,160,80)Traceback (most recent call last):...TurtleGraphicsError:bad color sequence: (240, 160, 80)>>>screen.colormode()1.0>>>screen.colormode(255)>>>screen.colormode()255>>>turtle.pencolor(240,160,80)

turtle.getcanvas()¶

Return the Canvas of this TurtleScreen. Useful for insiders who know what todo with a Tkinter Canvas.

>>>cv=screen.getcanvas()>>>cv<turtle.ScrolledCanvas object ...>

turtle.getshapes()¶

Return a list of names of all currently available turtle shapes.

>>>screen.getshapes()['arrow', 'blank', 'circle', ..., 'turtle']

turtle.register_shape(name,shape=None)¶

turtle.addshape(name,shape=None)¶

There are three different ways to call this function:

1. name is the name of a gif-file andshape isNone: Install thecorresponding image shape.

   >>>screen.register_shape("turtle.gif")

   Note

   Image shapesdo not rotate when turning the turtle, so they do notdisplay the heading of the turtle!

2. name is an arbitrary string andshape is a tuple of pairs ofcoordinates: Install the corresponding polygon shape.

   >>>screen.register_shape("triangle",((5,-3),(0,5),(-5,-3)))

3. name is an arbitrary string and shape is a (compound)Shapeobject: Install the corresponding compound shape.

Add a turtle shape to TurtleScreen’s shapelist. Only thusly registeredshapes can be used by issuing the commandshape(shapename).

turtle.turtles()¶

Return the list of turtles on the screen.

>>>forturtleinscreen.turtles():...turtle.color("red")

turtle.window_height()¶

Return the height of the turtle window.

>>>screen.window_height()480

turtle.window_width()¶

Return the width of the turtle window.

>>>screen.window_width()640

Methods specific to Screen, not inherited from TurtleScreen¶

turtle.bye()¶

Shut the turtlegraphics window.

turtle.exitonclick()¶

Bindbye() method to mouse clicks on the Screen.

If the value “using_IDLE” in the configuration dictionary isFalse(default value), also enter mainloop. Remark: If IDLE with the-n switch(no subprocess) is used, this value should be set toTrue inturtle.cfg. In this case IDLE’s own mainloop is active also for theclient script.

turtle.setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"])¶

Set the size and position of the main window. Default values of argumentsare stored in the configuration dictionary and can be changed via aturtle.cfg file.

Parameters

• width – if an integer, a size in pixels, if a float, a fraction of thescreen; default is 50% of screen

• height – if an integer, the height in pixels, if a float, a fraction ofthe screen; default is 75% of screen

• startx – if positive, starting position in pixels from the leftedge of the screen, if negative from the right edge, ifNone,center window horizontally

• starty – if positive, starting position in pixels from the topedge of the screen, if negative from the bottom edge, ifNone,center window vertically

>>>screen.setup(width=200,height=200,startx=0,starty=0)>>># sets window to 200x200 pixels, in upper left of screen>>>screen.setup(width=.75,height=0.5,startx=None,starty=None)>>># sets window to 75% of screen by 50% of screen and centers

turtle.title(titlestring)¶

Parameters

titlestring – a string that is shown in the titlebar of the turtlegraphics window

Set title of turtle window totitlestring.

>>>screen.title("Welcome to the turtle zoo!")

How to use help¶

The public methods of the Screen and Turtle classes are documented extensivelyvia docstrings. So these can be used as online-help via the Python helpfacilities:

• When using IDLE, tooltips show the signatures and first lines of thedocstrings of typed in function-/method calls.

• Callinghelp() on methods or functions displays the docstrings:

  >>>help(Screen.bgcolor)Help on method bgcolor in module turtle:bgcolor(self, *args) unbound turtle.Screen method    Set or return backgroundcolor of the TurtleScreen.    Arguments (if given): a color string or three numbers    in the range 0..colormode or a 3-tuple of such numbers.      >>> screen.bgcolor("orange")      >>> screen.bgcolor()      "orange"      >>> screen.bgcolor(0.5,0,0.5)      >>> screen.bgcolor()      "#800080">>>help(Turtle.penup)Help on method penup in module turtle:penup(self) unbound turtle.Turtle method    Pull the pen up -- no drawing when moving.    Aliases: penup | pu | up    No argument    >>> turtle.penup()

• The docstrings of the functions which are derived from methods have a modifiedform:

  >>>help(bgcolor)Help on function bgcolor in module turtle:bgcolor(*args)    Set or return backgroundcolor of the TurtleScreen.    Arguments (if given): a color string or three numbers    in the range 0..colormode or a 3-tuple of such numbers.    Example::      >>> bgcolor("orange")      >>> bgcolor()      "orange"      >>> bgcolor(0.5,0,0.5)      >>> bgcolor()      "#800080">>>help(penup)Help on function penup in module turtle:penup()    Pull the pen up -- no drawing when moving.    Aliases: penup | pu | up    No argument    Example:    >>> penup()

These modified docstrings are created automatically together with the functiondefinitions that are derived from the methods at import time.

Translation of docstrings into different languages¶

There is a utility to create a dictionary the keys of which are the method namesand the values of which are the docstrings of the public methods of the classesScreen and Turtle.

turtle.write_docstringdict(filename="turtle_docstringdict")¶

Parameters

filename – a string, used as filename

Create and write docstring-dictionary to a Python script with the givenfilename. This function has to be called explicitly (it is not used by theturtle graphics classes). The docstring dictionary will be written to thePython scriptfilename.py. It is intended to serve as a templatefor translation of the docstrings into different languages.

If you (or your students) want to useturtle with online help in yournative language, you have to translate the docstrings and save the resultingfile as e.g.turtle_docstringdict_german.py.

If you have an appropriate entry in yourturtle.cfg file this dictionarywill be read in at import time and will replace the original English docstrings.

At the time of this writing there are docstring dictionaries in German and inItalian. (Requests please toglingl@aon.at.)

How to configure Screen and Turtles¶

The built-in default configuration mimics the appearance and behaviour of theold turtle module in order to retain best possible compatibility with it.

If you want to use a different configuration which better reflects the featuresof this module or which better fits to your needs, e.g. for use in a classroom,you can prepare a configuration fileturtle.cfg which will be read at importtime and modify the configuration according to its settings.

The built in configuration would correspond to the following turtle.cfg:

width=0.5height=0.75leftright=Nonetopbottom=Nonecanvwidth=400canvheight=300mode=standardcolormode=1.0delay=10undobuffersize=1000shape=classicpencolor=blackfillcolor=blackresizemode=noresizevisible=Truelanguage=englishexampleturtle=turtleexamplescreen=screentitle=PythonTurtleGraphicsusing_IDLE=False

Short explanation of selected entries:

• The first four lines correspond to the arguments of theScreen.setup()method.

• Line 5 and 6 correspond to the arguments of the methodScreen.screensize().

• shape can be any of the built-in shapes, e.g: arrow, turtle, etc. For moreinfo tryhelp(shape).

• If you want to use no fillcolor (i.e. make the turtle transparent), you haveto writefillcolor="" (but all nonempty strings must not have quotes inthe cfg-file).

• If you want to reflect the turtle its state, you have to useresizemode=auto.

• If you set e.g.language=italian the docstringdictturtle_docstringdict_italian.py will be loaded at import time (ifpresent on the import path, e.g. in the same directory asturtle.

• The entriesexampleturtle andexamplescreen define the names of theseobjects as they occur in the docstrings. The transformation ofmethod-docstrings to function-docstrings will delete these names from thedocstrings.

• using_IDLE: Set this toTrue if you regularly work with IDLE and its -nswitch (“no subprocess”). This will preventexitonclick() to enter themainloop.

There can be aturtle.cfg file in the directory whereturtle isstored and an additional one in the current working directory. The latter willoverride the settings of the first one.

TheLib/turtledemo directory contains aturtle.cfg file. You canstudy it as an example and see its effects when running the demos (preferablynot from within the demo-viewer).