Patch #1513695: New turtle module, with demos.
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 30cb729..5185a8a 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -1,312 +1,2002 @@
-
+========================================
:mod:`turtle` --- Turtle graphics for Tk
========================================
-.. module:: turtle
- :platform: Tk
- :synopsis: An environment for turtle graphics.
-.. moduleauthor:: Guido van Rossum <guido@python.org>
+------------
+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 module turtle.py is an extended reimplementation of turtle.py from
+the Python standard distribution up to version Python 2.5.
+
+It tries to keep the merits of turtle.py 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 objectoriented interface uses essentially two+two classes:
+
+1. The TurtleScreen class defines graphics windows as a playground for the
+ drawing turtles. It's constructor needs a Tk-Canvas or a ScrolledCanvas
+ as argument. It should be used when turtle.py is used as part of some
+ application.
+
+ Derived from TurtleScreen is the subclass Screen. Screen is implemented
+ as sort of singleton, so there can exist only one instance of Screen at a
+ time. It should be used when turtle.py is used as a standalone tool for
+ doing graphics.
+
+ 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. It's constructor needs a Canvas/ScrolledCanvas/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 uses 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 automativally created
+whenever a function derived form 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 objectoriented
+interface.
+
+
+IMPORTANT NOTE!
+
+In the following documentation the argumentlist for functions is given.
+--->> Methods, of course, have the additional first argument self <<---
+--->> which is omitted here. <<---
+
+
+--------------------------------------------------
+OVERVIEW over available Turtle and Screen methods:
+--------------------------------------------------
+
+(A) TURTLE METHODS:
+===================
+
+I. TURTLE MOTION
+-----------------
+
+MOVE AND DRAW
+ forward | fd
+ back | 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
+
+II. 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
+
+III. TURTLE STATE
+-----------------
+
+VISIBILITY
+ showturtle | st
+ hideturtle | ht
+ isvisible
+
+APPEARANCE
+ shape
+ resizemode
+ shapesize | turtlesize
+ settiltangle
+ tiltangle
+ tilt
+
+IV. USING EVENTS
+----------------
+ onclick
+ onrelease
+ ondrag
+
+V. SPECIAL TURTLE METHODS
+-------------------------
+ begin_poly
+ end_poly
+ get_poly
+ clone
+ getturtle | getpen
+ getscreen
+ setundobuffer
+ undobufferentries
+ tracer
+ window_width
+ window_height
+
+..EXCURSUS ABOUT THE USE OF COMPOUND SHAPES
+..-----------------------------------------
+
+(B) METHODS OF TurtleScreen/Screen
+==================================
+
+I. WINDOW CONTROL
+-----------------
+ bgcolor
+ bgpic
+ clear | clearscreen
+ reset | resetscreen
+ screensize
+ setworldcoordinates
+
+II. ANIMATION CONTROL
+---------------------
+ delay
+ tracer
+ update
+
+III. USING SCREEN EVENTS
+------------------------
+ listen
+ onkey
+ onclick | onscreenclick
+ ontimer
+
+IV. SETTINGS AND SPECIAL METHODS
+--------------------------------
+ mode
+ colormode
+ getcanvas
+ getshapes
+ register_shape | addshape
+ turtles
+ window_height
+ window_width
+
+V. METHODS SPECIFIC TO Screen
+=============================
+ bye()
+ exitonclick()
+ setup()
+ title()
+
+---------------end of OVERVIEW ---------------------------
+
+
+
+2. METHODS OF RawTurtle/Turtle AND CORRESPONDING FUNCTIONS
+==========================================================
+
+(I) TURTLE MOTION:
+------------------
+
+(a) --- MOVE (AND DRAW)
+
+
+ .. method:: forward(distance)
+ .. method:: fd(distance)
+ distance -- a number (integer or float)
+
+ Move the turtle forward by the specified distance, in the direction
+ the turtle is headed.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.position()
+ (0.00, 0.00)
+ >>> turtle.forward(25)
+ >>> turtle.position()
+ (25.00,0.00)
+ >>> turtle.forward(-75)
+ >>> turtle.position()
+ (-50.00,0.00)
+
+
+ .. method:: back(distance)
+ .. method:: bk(distance)
+ .. method:: backward(distance)
+ distance -- a number
+
+ call: back(distance)
+ --or: bk(distance)
+ --or: backward(distance)
+
+ Move the turtle backward by distance ,opposite to the direction the
+ turtle is headed. Do not change the turtle's heading.
+
+ Example (for a Turtle instance named turtle)::
+
+ >>> turtle.position()
+ (0.00, 0.00)
+ >>> turtle.backward(30)
+ >>> turtle.position()
+ (-30.00, 0.00)
+
+
+ .. method:: right(angle)
+ .. method:: rt(angle)
+ angle -- a number (integer or float)
+
+ Turn turtle right by angle units. (Units are by default degrees,
+ but can be set via the degrees() and radians() functions.)
+ Angle orientation depends on mode. (See this.)
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.heading()
+ 22.0
+ >>> turtle.right(45)
+ >>> turtle.heading()
+ 337.0
+
+
+ .. method:: left(angle)
+ .. method:: lt(angle)
+ angle -- a number (integer or float)
+
+ Turn turtle left by angle units. (Units are by default degrees,
+ but can be set via the degrees() and radians() functions.)
+ Angle orientation depends on mode. (See this.)
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.heading()
+ 22.0
+ >>> turtle.left(45)
+ >>> turtle.heading()
+ 67.0
+
+ .. method:: goto(x, y=None)
+ .. method:: setpos(x, y=None)
+ .. method:: setposition(x, y=None)
+ x -- a number or a pair/vector of numbers
+ y -- a number None
+
+ call: goto(x, y) # two coordinates
+ --or: goto((x, y)) # a pair (tuple) of coordinates
+ --or: goto(vec) # e.g. as returned by pos()
+
+ Move turtle to an absolute position. If the pen is down,
+ draw line. Do not change the turtle's orientation.
+
+ Example (for a Turtle instance named turtle)::
+ >>> 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)
+
+
+ .. method:: setx(x)
+ x -- a number (integer or float)
+
+ Set the turtle's first coordinate to x, leave second coordinate
+ unchanged.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.position()
+ (0.00, 240.00)
+ >>> turtle.setx(10)
+ >>> turtle.position()
+ (10.00, 240.00)
+
+
+ .. method:: sety(y)
+ y -- a number (integer or float)
+
+ Set the turtle's first coordinate to x, leave second coordinate
+ unchanged.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.position()
+ (0.00, 40.00)
+ >>> turtle.sety(-10)
+ >>> turtle.position()
+ (0.00, -10.00)
+
+
+ .. method:: setheading(to_angle)
+ .. method:: seth(to_angle)
+ 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
+ =================== ====================
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.setheading(90)
+ >>> turtle.heading()
+ 90
+
+
+ .. method:: home():
+ Move turtle to the origin - coordinates (0,0) and set it's
+ heading to it's start-orientation (which depends on mode).
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.home()
+
+
+ .. method:: circle(radius, extent=None, steps=None)
+ radius -- a number
+ extent (optional) -- a number
+ steps (optional) -- an integer
+
+ 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. Maybe used to draw regular
+ polygons.
+
+ call: circle(radius) # full circle
+ --or: circle(radius, extent) # arc
+ --or: circle(radius, extent, steps)
+ --or: circle(radius, steps=6) # 6-sided polygon
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.circle(50)
+ >>> turtle.circle(120, 180) # semicircle
+
+
+ .. method:: dot(size=None, *color)
+ size -- an integer >= 1 (if given)
+ 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.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.dot()
+ >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
+
+
+ .. method:: 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).
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.color("blue")
+ >>> turtle.stamp()
+ 13
+ >>> turtle.fd(50)
+
+
+ .. method:: clearstamp(stampid):
+ stampid - an integer, must be return value of previous stamp() call.
+
+ Delete stamp with given stampid
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.color("blue")
+ >>> astamp = turtle.stamp()
+ >>> turtle.fd(50)
+ >>> turtle.clearstamp(astamp)
+
+
+ .. method:: clearstamps(n=None):
+ n -- an integer
+
+ Delete all or first/last n of turtle's stamps.
+ If n is None, delete all of pen's stamps,
+ else if n > 0 delete first n stamps
+ else if n < 0 delete last n stamps.
+
+ Example (for a Turtle instance named turtle)::
+ >>> for i in range(8):
+ ... turtle.stamp(); turtle.fd(30)
+ >>> turtle.clearstamps(2)
+ >>> turtle.clearstamps(-2)
+ >>> turtle.clearstamps()
+
+
+ .. method:: undo():
+ undo (repeatedly) the last turtle action(s). Number of available
+ undo actions is determined by the size of the undobuffer.
+
+ Example (for a Turtle instance named turtle)::
+ >>> for i in range(4):
+ turtle.fd(50); turtle.lt(80)
+
+ >>> for i in range(8):
+ turtle.undo()
+
+
+ .. method:: speed(speed=None):
+ 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 : *no* animation takes place. forward/back makes turtle jump
+ and likewise left/right make the turtle turn instantly.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.speed(3)
+
+
+TELL TURTLE'S STATE
+-------------------
+
+
+ .. method:: position()
+ .. method:: pos()
+ Return the turtle's current location (x,y) (as a Vec2D-vector)
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pos()
+ (0.00, 240.00)
+
+
+ .. method:: towards(x, y=None)
+ x -- a number or a pair/vector of numbers or a turtle instance
+ y -- a number None None
+
+ call: distance(x, y) # two coordinates
+ --or: distance((x, y)) # a pair (tuple) of coordinates
+ --or: distance(vec) # e.g. as returned by pos()
+ --or: distance(mypen) # where mypen is another turtle
+
+ Return the angle, between the line from turtle-position to position
+ specified by x, y and the turtle's start orientation. (Depends on
+ modes - "standard"/"world" or "logo")
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pos()
+ (10.00, 10.00)
+ >>> turtle.towards(0,0)
+ 225.0
+
+
+ .. method:: xcor()
+ Return the turtle's x coordinate
+
+ Example (for a Turtle instance named turtle)::
+ >>> reset()
+ >>> turtle.left(60)
+ >>> turtle.forward(100)
+ >>> print turtle.xcor()
+ 50.0
+
+
+ .. method:: ycor()
+ Return the turtle's y coordinate
+
+ Example (for a Turtle instance named turtle)::
+ >>> reset()
+ >>> turtle.left(60)
+ >>> turtle.forward(100)
+ >>> print turtle.ycor()
+ 86.6025403784
+
+
+ .. method:: heading()
+ Return the turtle's current heading (value depends on mode).
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.left(67)
+ >>> turtle.heading()
+ 67.0
+
+
+ .. method:: distance(x, y=None)
+ x -- a number or a pair/vector of numbers or a turtle instance
+ y -- a number None None
+
+ call: distance(x, y) # two coordinates
+ --or: distance((x, y)) # a pair (tuple) of coordinates
+ --or: distance(vec) # e.g. as returned by pos()
+ --or: distance(mypen) # where mypen is another turtle
+
+ Return the distance from the turtle to (x,y) in turtle step units.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pos()
+ (0.00, 0.00)
+ >>> turtle.distance(30,40)
+ 50.0
+ >>> joe = Turtle()
+ >>> joe.forward(77)
+ >>> turtle.distance(joe)
+ 77.0
+
+
+SETTINGS FOR MEASUREMENT
+
+
+ .. method:: degrees(fullcircle=360.0)
+ fullcircle - a number
+
+ Set angle measurement units, i. e. set number
+ of 'degrees' for a full circle. Dafault value is
+ 360 degrees.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.left(90)
+ >>> turtle.heading()
+ 90
+ >>> turtle.degrees(400.0) # angle measurement in gon
+ >>> turtle.heading()
+ 100
+
+
+ .. method:: radians()
+ Set the angle measurement units to radians.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.heading()
+ 90
+ >>> turtle.radians()
+ >>> turtle.heading()
+ 1.5707963267948966
+
+
+(II) PEN CONTROL:
+-----------------
+
+DRAWING STATE
+
+
+ .. method:: pendown()
+ .. method:: pd()
+ .. method:: down()
+ Pull the pen down -- drawing when moving.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pendown()
+
+
+ .. method:: penup()
+ .. method:: pu()
+ .. method:: up()
+ Pull the pen up -- no drawing when moving.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.penup()
+
+
+ .. method:: pensize(width=None)
+ .. method:: width(width=None)
+ width -- positive number
+
+ Set the line thickness to width or return it. If resizemode is set
+ to "auto" and turtleshape is a polygon, that polygon is drawn with
+ the same line thickness. If no argument is given, the current pensize
+ is returned.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pensize()
+ 1
+ turtle.pensize(10) # from here on lines of width 10 are drawn
+
+
+ .. method:: pen(pen=None, **pendict)
+ pen -- a dictionary with some or all of the below listed keys.
+ **pendict -- one or more keyword-arguments with the below
+ listed keys as keywords.
+
+ Return or set the pen's attributes in a 'pen-dictionary'
+ with the following key/value pairs:
+
+ * "shown" : True/False
+ * "pendown" : True/False
+ * "pencolor" : color-string or color-tuple
+ * "fillcolor" : color-string or color-tuple
+ * "pensize" : positive number
+ * "speed" : number in range 0..10
+ * "resizemode" : "auto" or "user" or "noresize"
+ * "stretchfactor": (positive number, positive number)
+ * "outline" : positive number
+ * "tilt" : number
+
+ This dicionary can be used as argument for a subsequent
+ pen()-call to restore the former pen-state. Moreover one
+ or more of these attributes can be provided as keyword-arguments.
+ This can be used to set several pen attributes in one statement.
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
+ >>> turtle.pen()
+ {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
+ 'pencolor': 'red', 'pendown': True, 'fillcolor': 'black',
+ 'stretchfactor': (1,1), 'speed': 3}
+ >>> penstate=turtle.pen()
+ >>> turtle.color("yellow","")
+ >>> turtle.penup()
+ >>> turtle.pen()
+ {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
+ 'pencolor': 'yellow', 'pendown': False, 'fillcolor': '',
+ 'stretchfactor': (1,1), 'speed': 3}
+ >>> p.pen(penstate, fillcolor="green")
+ >>> p.pen()
+ {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
+ 'pencolor': 'red', 'pendown': True, 'fillcolor': 'green',
+ 'stretchfactor': (1,1), 'speed': 3}
+
+
+ .. method:: isdown(self):
+ Return True if pen is down, False if it's up.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.penup()
+ >>> turtle.isdown()
+ False
+ >>> turtle.pendown()
+ >>> turtle.isdown()
+ True
+
+
+COLOR CONTROL
+
+
+ .. method:: color(*args)
+ Return or set pencolor and fillcolor.
+
+ Several input formats are allowed. They use 0, 1, 2, or 3 arguments
+ as follows:
+
+ - color()
+ Return the current pencolor and the current fillcolor
+ as a pair of color specification strings as are returned
+ by pencolor and fillcolor.
+ - color(colorstring), color((r,g,b)), color(r,g,b)
+ inputs as in pencolor, set both, fillcolor and pencolor,
+ to the given value.
+ - color(colorstring1, colorstring2),
+ - color((r1,g1,b1), (r2,g2,b2))
+ equivalent to pencolor(colorstring1) and fillcolor(colorstring2)
+ and analogously, if the other input format is used.
+
+ If turtleshape is a polygon, outline and interior of that polygon
+ is drawn with the newly set colors.
+ For more info see: pencolor, fillcolor
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.color('red', 'green')
+ >>> turtle.color()
+ ('red', 'green')
+ >>> colormode(255)
+ >>> color((40, 80, 120), (160, 200, 240))
+ >>> color()
+ ('#285078', '#a0c8f0')
+
+
+ .. method:: pencolor(*args)
+ Return or set the pencolor.
+
+ Four input formats are allowed:
+
+ - pencolor()
+ Return the current pencolor as color specification string,
+ possibly in hex-number format (see example).
+ May be used as input to another color/pencolor/fillcolor call.
+ - pencolor(colorstring)
+ s is a Tk color specification string, such as "red" or "yellow"
+ - pencolor((r, g, b))
+ *a tuple* of r, g, and b, which represent, an RGB color,
+ and each of r, g, and b are in the range 0..colormode,
+ where colormode is either 1.0 or 255
+ - pencolor(r, g, b)
+ r, g, and b represent an RGB color, and each of r, g, and b
+ are in the range 0..colormode
+
+ If turtleshape is a polygon, the outline of that polygon is drawn
+ with the newly set pencolor.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.pencolor('brown')
+ >>> tup = (0.2, 0.8, 0.55)
+ >>> turtle.pencolor(tup)
+ >>> turtle.pencolor()
+ '#33cc8c'
+
+
+ .. method:: fillcolor(*args)
+ """ Return or set the fillcolor.
+
+ Four input formats are allowed:
+
+ - fillcolor()
+ Return the current fillcolor as color specification string,
+ possibly in hex-number format (see example).
+ May be used as input to another color/pencolor/fillcolor call.
+ - fillcolor(colorstring)
+ s is a Tk color specification string, such as "red" or "yellow"
+ - fillcolor((r, g, b))
+ *a tuple* of r, g, and b, which represent, an RGB color,
+ and each of r, g, and b are in the range 0..colormode,
+ where colormode is either 1.0 or 255
+ - fillcolor(r, g, b)
+ r, g, and b represent an RGB color, and each of r, g, and b
+ are in the range 0..colormode
+
+ If turtleshape is a polygon, the interior of that polygon is drawn
+ with the newly set fillcolor.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.fillcolor('violet')
+ >>> col = turtle.pencolor()
+ >>> turtle.fillcolor(col)
+ >>> turtle.fillcolor(0, .5, 0)
+
+
+ See also: Screen method colormode()
+
+
+FILLING
+
+
+ .. method:: fill(flag)
+ flag -- True/False (or 1/0 respectively)
+
+ Call fill(True) before drawing the shape you want to fill,
+ and fill(False) when done. When used without argument: return
+ fillstate (True if filling, False else).
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.fill(True)
+ >>> for _ in range(3):
+ ... turtle.forward(100)
+ ... turtle.left(120)
+ ...
+ >>> turtle.fill(False)
+
+
+ .. method:: begin_fill()
+ Called just before drawing a shape to be filled.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.color("black", "red")
+ >>> turtle.begin_fill()
+ >>> turtle.circle(60)
+ >>> turtle.end_fill()
+
+
+ .. method:: end_fill()
+ Fill the shape drawn after the call begin_fill().
+
+ Example: See begin_fill()
+
+
+MORE DRAWING CONTROL
+
+
+ .. method:: reset()
+ Delete the turtle's drawings from the screen, re-center the turtle
+ and set variables to the default values.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.position()
+ (0.00,-22.00)
+ >>> turtle.heading()
+ 100.0
+ >>> turtle.reset()
+ >>> turtle.position()
+ (0.00,0.00)
+ >>> turtle.heading()
+ 0.0
+
+
+ .. method:: clear()
+ Delete the turtle's drawings from the screen. Do not move turtle.
+ State and position of the turtle as well as drawings of other
+ turtles are not affected.
+
+ Examples (for a Turtle instance named turtle):
+ >>> turtle.clear()
+
+
+ .. method:: write(arg, move=False, align='left', font=('Arial', 8, 'normal'))
+ arg -- info, which is to be written to the TurtleScreen
+ move (optional) -- True/False
+ align (optional) -- one of the strings "left", "center" or right"
+ font (optional) -- a triple (fontname, fontsize, fonttype)
+
+ Write text - the string representation of arg - at the current
+ turtle position according to align ("left", "center" or right")
+ and with the given font.
+ If move is True, the pen is moved to the bottom-right corner
+ of the text. By default, move is False.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.write('Home = ', True, align="center")
+ >>> turtle.write((0,0), True)
+
+
+TURTLE STATE:
+-------------
+
+VISIBILITY
+
+
+ .. method:: showturtle()
+ .. method:: st()
+ Makes the turtle visible.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.hideturtle()
+ >>> turtle.showturtle()
+
+
+ .. method:: hideturtle()
+ .. method:: ht()
+ Makes the turtle invisible.
+ It's a good idea to do this while you're in the middle of
+ doing some complex drawing, because hiding the turtle speeds
+ up the drawing observably.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.hideturtle()
+
+
+ .. method:: isvisible(self):
+ Return True if the Turtle is shown, False if it's hidden.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.hideturtle()
+ >>> print turtle.isvisible():
+ False
+
+
+APPEARANCE
+
+
+ .. method:: shape(name=None)
+ name -- a string, which is a valid shapename
+
+ Set turtle shape to shape with given name or, if name is not given,
+ return name of current shape.
+ Shape with name must exist in the TurtleScreen's shape dictionary.
+ Initially there are the following polygon shapes:
+ 'arrow', 'turtle', 'circle', 'square', 'triangle', 'classic'.
+ To learn about how to deal with shapes see Screen-method register_shape.
+
+ Example (for a Turtle instance named turtle)::
+ >>> turtle.shape()
+ 'arrow'
+ >>> turtle.shape("turtle")
+ >>> turtle.shape()
+ 'turtle'
+
+
+ .. method:: resizemode(rmode=None)
+ rmode -- one of the strings "auto", "user", "noresize"
+
+ Set resizemode to one of the values: "auto", "user", "noresize".
+ If rmode is not given, return current resizemode.
+ Different resizemodes have the following effects:
+
+ - "auto" adapts the appearance of the turtle
+ corresponding to the value of pensize.
+ - "user" adapts the appearance of the turtle according to the
+ values of stretchfactor and outlinewidth (outline),
+ which are set by shapesize()
+ - "noresize" no adaption of the turtle's appearance takes place.
+
+ resizemode("user") is called by a shapesize when used with arguments.
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.resizemode("noresize")
+ >>> turtle.resizemode()
+ 'noresize'
+
+
+ .. method:: shapesize(stretch_wid=None, stretch_len=None, outline=None):
+ stretch_wid -- positive number
+ stretch_len -- positive number
+ outline -- positive number
+
+ Return or set the pen's attributes x/y-stretchfactors and/or outline.
+ Set resizemode to "user".
+ If and only if resizemode is set to "user", the turtle will be
+ displayed stretched according to its stretchfactors:
+ stretch_wid is stretchfactor perpendicular to it's orientation,
+ stretch_len is stretchfactor in direction of it's orientation,
+ outline determines the width of the shapes's outline.
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.resizemode("user")
+ >>> turtle.shapesize(5, 5, 12)
+ >>> turtle.shapesize(outline=8)
+
+
+ .. method:: tilt(angle)
+ angle - a number
+
+ Rotate the turtleshape by angle from its current tilt-angle,
+ but do NOT change the turtle's heading (direction of movement).
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.shape("circle")
+ >>> turtle.shapesize(5,2)
+ >>> turtle.tilt(30)
+ >>> turtle.fd(50)
+ >>> turtle.tilt(30)
+ >>> turtle.fd(50)
+
+
+ .. method:: settiltangle(angle)
+ angle -- number
+
+ Rotate the turtleshape to point in the direction specified by angle,
+ regardless of its current tilt-angle. DO NOT change the turtle's
+ heading (direction of movement).
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.shape("circle")
+ >>> turtle.shapesize(5,2)
+ >>> turtle.settiltangle(45)
+ >>> stamp()
+ >>> turtle.fd(50)
+ >>> turtle.settiltangle(-45)
+ >>> stamp()
+ >>> turtle.fd(50)
+
+
+ .. method:: tiltangle()
+ Return the current tilt-angle, i. e. the angle between the
+ orientation of the turtleshape and the heading of the turtle
+ (it's direction of movement).
+
+ Examples (for a Turtle instance named turtle)::
+ >>> turtle.shape("circle")
+ >>> turtle.shapesize(5,2)
+ >>> turtle.tilt(45)
+ >>> turtle.tiltangle()
+ 45
+
+
+IV. USING EVENTS
+----------------
+
+
+ .. method:: onclick(fun, btn=1, add=None)
+ fun -- a function with two arguments, to which will be assigned
+ the coordinates of the clicked point on the canvas.
+ num -- number of the mouse-button defaults to 1 (left mouse button).
+ add -- True or False. If True, new binding will be added, otherwise
+ it will replace a former binding.
+
+ Bind fun to mouse-click event on this turtle on canvas.
+ If fun is None, existing bindings are removed.
+ Example for the anonymous turtle, i. e. the procedural way::
+
+ >>> def turn(x, y):
+ left(360)
+
+ >>> onclick(turn) # Now clicking into the turtle will turn it.
+ >>> onclick(None) # event-binding will be removed
+
+
+ .. method:: onrelease(fun, btn=1, add=None):
+ """
+ Arguments:
+ fun -- a function with two arguments, to which will be assigned
+ the coordinates of the clicked point on the canvas.
+ num -- number of the mouse-button defaults to 1 (left mouse button).
+ add -- True or False. If True, new binding will be added, otherwise
+ it will replace a former binding.
+
+ Bind fun to mouse-button-release event on this turtle on canvas.
+ If fun is None, existing bindings are removed.
+
+ Example (for a MyTurtle instance named turtle):
+ >>> class MyTurtle(Turtle):
+ ... def glow(self,x,y):
+ ... self.fillcolor("red")
+ ... def unglow(self,x,y):
+ ... self.fillcolor("")
+ ...
+ >>> turtle = MyTurtle()
+ >>> turtle.onclick(turtle.glow)
+ >>> turtle.onrelease(turtle.unglow)
+ ### clicking on turtle turns fillcolor red,
+ ### unclicking turns it to transparent.
+
+
+ .. method:: ondrag(fun, btn=1, add=None):
+ fun -- a function with two arguments, to which will be assigned
+ the coordinates of the clicked point on the canvas.
+ num -- number of the mouse-button defaults to 1 (left mouse button).
+ add -- True or False. If True, new binding will be added, otherwise
+ it will replace a former binding.
+
+ Bind fun to mouse-move event on this turtle on canvas.
+ If fun is None, existing bindings are removed.
+
+ Remark: Every sequence of mouse-move-events on a turtle is preceded
+ by a mouse-click event on that turtle.
+ If fun is None, existing bindings are removed.
+
+ Example (for a Turtle instance named turtle):
+ >>> turtle.ondrag(turtle.goto)
+ ### Subsequently clicking and dragging a Turtle will move it across
+ ### the screen thereby producing handdrawings (if pen is down).
+
+
+V. SPECIAL TURTLE METHODS
+--------------------------
+
+
+ .. method:: begin_poly():
+ Start recording the vertices of a polygon. Current turtle position
+ is first vertex of polygon.
+
+ Example (for a Turtle instance named turtle):
+ >>> turtle.begin_poly()
+
+
+ .. method:: end_poly():
+ Stop recording the vertices of a polygon. Current turtle position is
+ last vertex of polygon. This will be connected with the first vertex.
+
+ Example (for a Turtle instance named turtle):
+ >>> turtle.end_poly()
+
+
+ .. method:: get_poly():
+ Return the lastly recorded polygon.
+
+ Example (for a Turtle instance named turtle):
+ >>> p = turtle.get_poly()
+ >>> turtle.register_shape("myFavouriteShape", p)
+
+
+ .. method:: clone():
+ Create and return a clone of the turtle with same position, heading
+ and turtle properties.
+
+ Example (for a Turtle instance named mick):
+ mick = Turtle()
+ joe = mick.clone()
+
+
+ .. method:: getturtle():
+ Return the Turtleobject itself.
+ Only reasonable use: as a function to return the 'anonymous turtle':
+
+ Example:
+ >>> pet = getturtle()
+ >>> pet.fd(50)
+ >>> pet
+ <turtle.Turtle object at 0x01417350>
+ >>> turtles()
+ [<turtle.Turtle object at 0x01417350>]
+
+
+ .. method:: getscreen():
+ Return the TurtleScreen object, the turtle is drawing on.
+ So TurtleScreen-methods can be called for that object.
+
+ Example (for a Turtle instance named turtle):
+ >>> ts = turtle.getscreen()
+ >>> ts
+ <turtle.Screen object at 0x01417710>
+ >>> ts.bgcolor("pink")
+
+
+ .. method:: def setundobuffer(size):
+ size -- an integer or None
+
+ Set or disable undobuffer.
+ If size is an integer an empty undobuffer of given size is installed.
+ Size gives the maximum number of turtle-actions that can be undone
+ by the undo() method/function.
+ If size is None, no undobuffer is present.
+
+ Example (for a Turtle instance named turtle):
+ >>> turtle.setundobuffer(42)
+
+
+ .. method:: undobufferentries():
+ """Return count of entries in the undobuffer.
+
+ Example (for a Turtle instance named turtle):
+ >>> while undobufferentries():
+ ... undo()
+
+
+ .. method:: tracer(flag=None, delay=None)
+ A replica of the corresponding TurtleScreen-method
+ *Deprecated since Python 2.6* (as RawTurtle method)
+
+ .. method:: window_width()
+ .. method:: window_height()
+ Both are replicas of the corresponding TurtleScreen-methods
+ *Deprecated since Python 2.6* (as RawTurtle methods)
+
-.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
+EXCURSUS ABOUT THE USE OF COMPOUND SHAPES
+-----------------------------------------
+To use compound turtle shapes, which consist of several polygons
+of different color, you must use the helper class Shape
+explicitely as described below:
-The :mod:`turtle` module provides turtle graphics primitives, in both an
-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.
+ 1. Create an empty Shape object of type compound
+ 2. Add as many components to this object as desired,
+ using the addcomponent() method:
+
+ .. method:: addcomponent(self, poly, fill, outline=None)
+ poly -- a polygon
+ fill -- a color, the poly will be filled with
+ outline -- a color for the poly's outline (if given)
+
+So it goes like this::
-The procedural interface uses a pen and a canvas which are automagically created
-when any of the functions are called.
+ >>> 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")
-The :mod:`turtle` module defines the following functions:
+Now add Shape s to the Screen's shapelist ...
+.. and use it::
+ >>> register_shape("myshape", s)
+ >>> shape("myshape")
+
-.. function:: degrees()
+NOTE 1: addcomponent() is a method of class Shape (not of
+Turtle nor Screen) and thus there is NO FUNCTION of the same name.
- Set angle measurement units to degrees.
+NOTE 2: class Shape is used internally by the register_shape method
+in different ways.
+The application programmer has to deal with the Shape class
+ONLY when using compound shapes like shown above!
-.. function:: radians()
+NOTE 3: A short description of the class Shape is in section 4.
- Set angle measurement units to radians.
+
+
+3. METHODS OF TurtleScreen/Screen AND CORRESPONDING FUNCTIONS
+=============================================================
-.. function:: setup(**kwargs)
+WINDOW CONTROL
+--------------
- 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.
+ .. method:: bgcolor(*args)
+ args -- a color string or three numbers in the range 0..colormode
+ or a 3-tuple of such numbers.
- * ``height``: either a size in pixels or a fraction of the screen. The default
- is 50% of the screen.
+ Set or return backgroundcolor of the TurtleScreen.
+
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.bgcolor("orange")
+ >>> screen.bgcolor()
+ 'orange'
+ >>> screen.bgcolor(0.5,0,0.5)
+ >>> screen.bgcolor()
+ '#800080'
- * ``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.
+ .. method:: bgpic(picname=None)
+ picname -- a string, name of a gif-file or "nopic".
+
+ Set background image or return name of current backgroundimage.
+ If picname is a filename, set the corresponing image as background.
+ If picname is "nopic", delete backgroundimage, if present.
+ If picname is None, return the filename of the current backgroundimage.
+
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.bgpic()
+ 'nopic'
+ >>> screen.bgpic("landscape.gif")
+ >>> screen.bgpic()
+ 'landscape.gif'
- Examples::
- # Uses default geometry: 50% x 50% of screen, centered.
- setup()
+ .. method:: clear()
+ .. method:: clearscreen()
+ Delete all drawings and all turtles from the TurtleScreen.
+ Reset empty TurtleScreen to it's initial state: white background,
+ no backgroundimage, no eventbindings and tracing on.
- # Sets window to 200x200 pixels, in upper left of screen
- setup (width=200, height=200, startx=0, starty=0)
+ Example (for a TurtleScreen instance named screen):
+ screen.clear()
- # Sets window to 75% of screen by 50% of screen, and centers it.
- setup(width=.75, height=0.5, startx=None, starty=None)
+ *Note*: this method is only available as the function named
+ clearscreen(). (The function clear() is another one derived from
+ the Turtle-method clear()!).
-.. function:: title(title_str)
+ .. method:: reset()
+ .. method:: resetscreen()
+ Reset all Turtles on the Screen to their initial state.
- Set the window's title to *title*.
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.reset()
+ *Note*: this method is pnly available as the function named
+ resetscreen(). (The function reset() is another one derived from
+ the Turtle-method reset()!).
-.. function:: done()
- Enters the Tk main loop. The window will continue to be displayed until the
- user closes it or the process is killed.
+ .. method:: screensize(canvwidth=None, canvheight=None, bg=None):
+ canvwidth -- positive integer, new width of canvas in pixels
+ canvheight -- positive integer, new height of canvas in pixels
+ bg -- colorstring or color-tupel, new backgroundcolor
+
+ If no arguments are given, return current (canvaswidth, canvasheight)
+ Resize the canvas, the turtles are drawing on.
+ Do not alter the drawing window. To observe hidden parts of
+ the canvas use the scrollbars. (So one can make visible those
+ parts of a drawing, which were outside the canvas before!)
+ Example (for a Turtle instance named turtle):
+ >>> turtle.screensize(2000,1500)
+ ### e. g. to search for an erroneously escaped turtle ;-)
+
+
+ .. method:: setworldcoordinates(llx, lly, urx, ury):
+ 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
-.. function:: reset()
+ Set up user coodinate-system and switch to mode 'world' if necessary.
+ This performs a screen.reset. If mode 'world' is already active,
+ all drawings are redrawn according to the new coordinates.
- Clear the screen, re-center the pen, and set variables to the default values.
+ But *ATTENTION*: in user-defined coordinatesystems angles may appear
+ distorted. (see Screen.mode())
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.reset()
+ >>> screen.setworldcoordinates(-50,-7.5,50,7.5)
+ >>> for _ in range(72):
+ ... left(10)
+ ...
+ >>> for _ in range(8):
+ ... left(45); fd(2) # a regular octogon
+
+
+ANIMATION CONTROL
+-----------------
-.. function:: clear()
- Clear the screen.
+ .. method:: delay(delay=None):
+ delay -- positive integer
+
+ Set or return the drawing delay in milliseconds. (This is sort of
+ time interval between two consecutived canvas updates.) The longer
+ the drawing delay, the slower the animation.
+ Optional argument:
+ Example (for a TurtleScreen instance named screen)::
-.. function:: tracer(flag)
+ >>> screen.delay(15)
+ >>> screen.delay()
+ 15
- 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.
+ .. method:: tracer(n=None, delay=None):
+ n -- nonnegative integer
+ delay -- nonnegative integer
+
+ Turn turtle animation on/off and set delay for update drawings.
+ If n is given, only each n-th regular screen update is really performed.
+ (Can be used to accelerate the drawing of complex graphics.)
+ Second argument sets delay value (see delay())
-.. function:: speed(speed)
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.tracer(8, 25)
+ >>> dist = 2
+ >>> for i in range(200):
+ ... fd(dist)
+ ... rt(90)
+ ... dist += 2
+
+
+ .. method:: update():
+ Perform a TurtleScreen update. To be used, when tracer is turned
+ off.
+
+ See also RawTurtle/Turtle - method 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).
+USING SCREEN EVENTS
+-------------------
- .. versionadded:: 2.5
+ .. method:: listen(xdummy=None, ydummy=None):
+ """Set focus on TurtleScreen (in order to collect key-events)
+ Dummy arguments are provided in order to be able to pass listen
+ to the onclick method.
-.. function:: delay(delay)
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.listen()
- Set the speed of the turtle to *delay*, which is given in ms.
- .. versionadded:: 2.5
+ .. method:: onkey(fun, key):
+ fun -- a function with no arguments or None
+ key -- a string: key (e.g. "a") or key-symbol (e.g. "space")
+ Bind fun to key-release event of key. If fun is None, event-bindings
+ are removed.
+ Remark: in order to be able to register key-events, TurtleScreen
+ must have focus. (See method listen.)
-.. function:: forward(distance)
+ Example (for a TurtleScreen instance named screen
+ and a Turtle instance named turtle)::
- Go forward *distance* steps.
+ >>> def f():
+ ... fd(50)
+ ... lt(60)
+ ...
+ >>> screen.onkey(f, "Up")
+ >>> screen.listen()
+
+
+ .. method:: onclick(fun, btn=1, add=None):
+ .. method:: onscreenclick(fun, btn=1, add=None):
+ fun -- a function with two arguments, to which will be assigned
+ the coordinates of the clicked point on the canvas - or None.
+ num -- number of the mouse-button defaults to 1 (left mouse button).
+ add -- True or False. If True, new binding will be added, otherwise
+ it will replace a former binding.
+ Example (for a TurtleScreen instance named screen and a Turtle instance
+ named turtle)::
-.. function:: backward(distance)
+ >>> screen.onclick(turtle.goto)
+ ### Subsequently clicking into the TurtleScreen will
+ ### make the turtle move to the clicked point.
+ >>> screen.onclick(None)
+
+ ### event-binding will be removed
- Go backward *distance* steps.
+ *Note*: this method is only available as the function named
+ onscreenclick(). (The function onclick() is a different one derived
+ from the Turtle-method onclick()!).
-.. function:: left(angle)
+ .. method:: ontimer(fun, t=0):
+ fun -- a function with no arguments.
+ t -- a number >= 0
- Turn left *angle* units. Units are by default degrees, but can be set via the
- :func:`degrees` and :func:`radians` functions.
+ Install a timer, which calls fun after t milliseconds.
+ Example (for a TurtleScreen instance named screen):
-.. function:: right(angle)
+ >>> running = True
+ >>> def f():
+ if running:
+ fd(50)
+ lt(60)
+ screen.ontimer(f, 250)
+ >>> f() ### makes the turtle marching around
+ >>> running = False
- Turn right *angle* units. Units are by default degrees, but can be set via the
- :func:`degrees` and :func:`radians` functions.
+SETTINGS AND SPECIAL METHODS
-.. function:: up()
- Move the pen up --- stop drawing.
+ .. method:: mode(mode=None):
+ mode -- on of the strings 'standard', 'logo' or 'world'
+
+ Set turtle-mode ('standard', 'logo' or 'world') and perform reset.
+ If mode is not given, current mode is returned.
+ Mode 'standard' is compatible with old turtle.py.
+ Mode 'logo' is compatible with most Logo-Turtle-Graphics.
+ Mode 'world' uses userdefined 'worldcoordinates'. *Attention*: in
+ this mode angles appear distorted if x/y unit-ratio doesn't equal 1.
-.. function:: down()
+ ============ ========================= ===================
+ Mode Initial turtle heading positive angles
+ ============ ========================= ===================
+ 'standard' to the right (east) counterclockwise
+ 'logo' upward (north) clockwise
+ ============ ========================= ===================
- Move the pen down --- draw when moving.
+ Examples::
+ >>> mode('logo') # resets turtle heading to north
+ >>> mode()
+ 'logo'
-.. function:: width(width)
+ .. method:: colormode(cmode=None):
+ cmode -- one of the values 1.0 or 255
- Set the line width to *width*.
+ """Return the colormode or set it to 1.0 or 255.
+ Subsequently r, g, b values of colortriples have to be in
+ range 0..cmode.
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.colormode()
+ 1.0
+ >>> screen.colormode(255)
+ >>> turtle.pencolor(240,160,80)
-.. function:: 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]).
+ .. method:: getcanvas():
+ Return the Canvas of this TurtleScreen. Useful for insiders, who
+ know what to do with a Tkinter-Canvas ;-)
+ Example (for a Screen instance named screen):
+ >>> cv = screen.getcanvas()
+ >>> cv
+ <turtle.ScrolledCanvas instance at 0x010742D8>
-.. function:: 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.
+ .. method:: getshapes():
+ """Return a list of names of all currently available turtle shapes.
+
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.getshapes()
+ ['arrow', 'blank', 'circle', ... , 'turtle']
-.. function:: fill(flag)
+ .. method:: register_shape(name, shape=None)
+ .. method:: addshape(name, shape=None)
+ Arguments:
+ (1) name is the name of a gif-file and shape is None.
+ Installs the corresponding image shape.
+ !! Image-shapes DO NOT rotate when turning the turtle,
+ !! so they do not display the heading of the turtle!
+ (2) name is an arbitrary string and shape is a tuple
+ of pairs of coordinates. Installs the corresponding
+ polygon shape
+ (3) name is an arbitrary string and shape is a
+ (compound) Shape object. Installs the corresponding
+ compound shape. (See class Shape.)
+
+ Adds a turtle shape to TurtleScreen's shapelist. Only thusly
+ registered shapes can be used by issueing the command shape(shapename).
- 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.
+ call: register_shape("turtle.gif")
+ --or: register_shape("tri", ((0,0), (10,10), (-10,10)))
+
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.register_shape("triangle", ((5,-3),(0,5),(-5,-3)))
-.. function:: begin_fill()
+ .. method:: turtles():
+ Return the list of turtles on the screen.
- Switch turtle into filling mode; Must eventually be followed by a corresponding
- end_fill() call. Otherwise it will be ignored.
+ Example (for a TurtleScreen instance named screen):
+ >>> for turtle in screen.turtles()
+ ... turtle.color("red")
- .. versionadded:: 2.5
+ .. method:: window_height():
+ Return the height of the turtle window.
-.. function:: end_fill()
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.window_height()
+ 480
- End filling mode, and fill the shape; equivalent to ``fill(0)``.
- .. versionadded:: 2.5
+ .. method:: window_width():
+ Return the width of the turtle window.
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.window_width()
+ 640
+
-.. function:: circle(radius[, extent])
+METHODS SPECIFIC TO Screen, not inherited from TurtleScreen
+-----------------------------------------------------------
- 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*.
+ .. method:: bye():
+ """Shut the turtlegraphics window.
+ This is a method of the Screen-class and not available for
+ TurtleScreen instances.
-.. function:: goto(x, y)
- goto((x, y))
+ Example (for a TurtleScreen instance named screen):
+ >>> screen.bye()
- Go to co-ordinates *x*, *y*. The co-ordinates may be specified either as two
- separate arguments or as a 2-tuple.
+ .. method:: exitonclick():
+ Bind bye() method to mouseclick on TurtleScreen.
+ If "using_IDLE" - value in configuration dictionary is False
+ (default value), enter mainloop.
+ Remark: If IDLE with -n switch (no subprocess) is used, this value
+ should be set to True in turtle.cfg. In this case IDLE's own mainloop
+ is active also for the client script.
-.. function:: towards(x, y)
+ This is a method of the Screen-class and not available for
+ TurtleScreen instances.
- 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.
+ Example (for a Screen instance named screen):
+ >>> screen.exitonclick()
- .. versionadded:: 2.5
+ .. method:: 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 arguments are stored in the configuration dicionary
+ and can be changed via a turtle.cfg file.
+
+ width -- as integer a size in pixels, as float a fraction of the screen.
+ Default is 50% of screen.
+ height -- as integer the height in pixels, as float a fraction of the
+ screen. Default is 75% of screen.
+ startx -- if positive, starting position in pixels from the left
+ edge of the screen, if negative from the right edge
+ Default, startx=None is to center window horizontally.
+ starty -- if positive, starting position in pixels from the top
+ edge of the screen, if negative from the bottom edge
+ Default, starty=None is to center window vertically.
-.. function:: heading()
+ Examples (for a Screen instance named screen)::
+ >>> screen.setup (width=200, height=200, startx=0, starty=0)
+ # sets window to 200x200 pixels, in upper left of screen
- Return the current orientation of the turtle.
+ >>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
+ # sets window to 75% of screen by 50% of screen and centers
- .. versionadded:: 2.3
+
+ .. method:: title(titlestring):
+ titlestring -- a string, to appear in the titlebar of the
+ turtle graphics window.
+ Set title of turtle-window to titlestring
-.. function:: setheading(angle)
+ This is a method of the Screen-class and not available for
+ TurtleScreen instances.
- Set the orientation of the turtle to *angle*.
+ Example (for a Screen instance named screen):
+ >>> screen.title("Welcome to the turtle-zoo!")
- .. versionadded:: 2.3
-.. function:: position()
+4. THE PUBLIC CLASSES of the module turtle.py
+=============================================
- Return the current location of the turtle as an ``(x,y)`` pair.
- .. versionadded:: 2.3
+class RawTurtle(canvas):
+ canvas -- a Tkinter-Canvas, a ScrolledCanvas or a TurtleScreen
+
+ Alias: RawPen
+
+ Define a turtle.
+ A description of the methods follows below. All methods are also
+ available as functions (to control some anonymous turtle) thus
+ providing a procedural interface to turtlegraphics
+
+class Turtle()
+ Subclass of RawTurtle, has the same interface with the additional
+ property, that Turtle instances draw on a default Screen object,
+ which is created automatically, when needed for the first time.
+
+class TurtleScreen(cv)
+ cv -- a Tkinter-Canvas
+ Provides screen oriented methods like setbg etc.
+ A description of the methods follows below.
+
+class Screen()
+ Subclass of TurtleScreen, with four methods added.
+ All methods are also available as functions to conrtol a unique
+ Screen instance thus belonging to the procedural interface
+ to turtlegraphics. This Screen instance is automatically created
+ when needed for the first time.
+class ScrolledCavas(master)
+ master -- some Tkinter widget to contain the ScrolledCanvas, i.e.
+ a Tkinter-canvas with scrollbars added.
+ Used by class Screen, which thus provides automatically a
+ ScrolledCanvas as playground for the turtles.
-.. function:: setx(x)
+class Shape(type\_, data)
+ type --- one of the strings "polygon", "image", "compound"
- Set the x coordinate of the turtle to *x*.
+ Data structure modeling shapes.
+ The pair type\_, data must be as follows:
+
+ type\_ data
- .. versionadded:: 2.3
+ "polygon" a polygon-tuple, i. e.
+ a tuple of pairs of coordinates
+
+ "image" an image (in this form only used internally!)
+
+ "compound" None
+ A compund shape has to be constructed using
+ the addcomponent method
+
+ addcomponent(self, poly, fill, outline=None)
+ poly -- polygon, i. e. a tuple of pairs of numbers.
+ fill -- the fillcolor of the component,
+ outline -- the outline color of the component.
+ Example:
+ >>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
+ >>> s = Shape("compound")
+ >>> s.addcomponent(poly, "red", "blue")
+ ### .. add more components and then use register_shape()
+
+ See EXCURSUS ABOUT THE USE OF COMPOUND SHAPES
+
-.. function:: sety(y)
+class Vec2D(x, y):
+ A two-dimensional vector class, used as a helper class
+ for implementing turtle graphics.
+ May be useful for turtle graphics programs also.
+ Derived from tuple, so a vector is a tuple!
- Set the y coordinate of the turtle to *y*.
+ Provides (for a, b vectors, k number):
- .. versionadded:: 2.3
+ * a+b vector addition
+ * a-b vector subtraction
+ * a*b inner product
+ * k*a and a*k multiplication with scalar
+ * \|a\| absolute value of a
+ * a.rotate(angle) rotation
-.. function:: window_width()
+
+V. HELP AND CONFIGURATION
+=========================
- Return the width of the canvas window.
+This section contains subsections on:
- .. versionadded:: 2.3
+- how to use help
+- how to prepare and use translations of the online-help
+ into other languages
+- how to configure the appearance of the graphics window and
+ the turtles at startup
-.. function:: window_height()
+HOW TO USE HELP:
+----------------
- Return the height of the canvas window.
+The public methods of the Screen and Turtle classes are documented
+extensively via docstrings. So these can be used as online-help
+via the Python help facilities:
- .. versionadded:: 2.3
+- When using IDLE, tooltips show the signatures and first lines of
+ the docstrings of typed in function-/method calls.
-This module also does ``from math import *``, so see the documentation for the
-:mod:`math` module for additional constants and functions useful for turtle
-graphics.
+- calling help on methods or functions display the docstrings.
+ Examples::
+
+ >>> 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.
+
+ Example (for a TurtleScreen instance named screen)::
+
+ >>> 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
+
+ Example (for a Turtle instance named turtle):
+ >>> turtle.penup()
+The docstrings of the functions which are derived from methods have
+a modified form::
-.. function:: demo()
+ >>> 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()
- Exercise the module a bit.
+These modified docstrings are created automatically together with the
+function definitions that are derived from the methods at import time.
-.. exception:: Error
+TRANSLATION OF DOCSTRINGS INTO DIFFERENT LANGUAGES
+--------------------------------------------------
- Exception raised on any error caught by this module.
+There is a utility to create a dictionary the keys of which are the
+method names and the values of which are the docstrings of the public
+methods of the classes Screen and Turtle.
-For examples, see the code of the :func:`demo` function.
+write_docstringdict(filename="turtle_docstringdict"):
+ filename -- a string, used as filename
-This module defines the following classes:
+ Create and write docstring-dictionary to a Python script
+ with the given filename.
+ This function has to be called explicitely, (it is not used by the
+ turtle-graphics classes). The docstring dictionary will be written
+ to the Python script <filname>.py It is intended to serve as a
+ template for translation of the docstrings into different languages.
+If you (or your students) want to use turtle.py with online help in
+your native language. You have to translate the docstrings and save
+the resulting file as e.g. turtle_docstringdict_german.py
-.. class:: Pen()
+If you have an appropriate entry in your turtle.cfg file this dictionary
+will be read in at import time and will replace the original English
+docstrings.
- 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.
+At the time of this writing there exist docstring_dicts in German
+and in Italian. (Requests please to glingl@aon.at)
+
+
+HOW TO CONFIGURE SCREEN AND TURTLES
+-----------------------------------
-.. class:: Turtle()
+The built-in default configuration mimics the appearance and
+behaviour of the old turtle module in order to retain best possible
+compatibility with it.
- Define a pen. This is essentially a synonym for ``Pen()``; :class:`Turtle` is an
- empty subclass of :class:`Pen`.
+If you want to use a different configuration which reflects
+better the features of this module or which fits better to
+your needs, e. g. for use in a classroom, you can prepare
+a configuration file turtle.cfg which will be read at import
+time and modify the configuration according to it's settings.
+The built in configuration would correspond to the following
+turtle.cfg:
-.. class:: RawPen(canvas)
+width = 0.5
+height = 0.75
+leftright = None
+topbottom = None
+canvwidth = 400
+canvheight = 300
+mode = standard
+colormode = 1.0
+delay = 10
+undobuffersize = 1000
+shape = classic
+pencolor = black
+fillcolor = black
+resizemode = noresize
+visible = True
+language = english
+exampleturtle = turtle
+examplescreen = screen
+title = Python Turtle Graphics
+using_IDLE = False
- 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.
+Short explanation of selected entries:
+- The first four lines correspond to the arguments of the
+ Screen.setup method
+- Line 5 and 6 correspond to the arguments of the Method
+ Screen.screensize
+- shape can be any of the built-in shapes, e.g: arrow, turtle,
+ etc. For more info try help(shape)
+- if you want to use no fillcolor (i. e. turtle transparent),
+ you have to write:
+ fillcolor = ""
+ (All not empty strings must not have quotes in the cfg-file!)
+- if you want to reflect the turtle its state, you have to use
+ resizemode = auto
+- if you set, e. g.: language = italian
+ the docstringdict turtle_docstringdict_italian.py will be
+ loaded at import time (if present on the import path, e.g. in
+ the same directory as turtle.py
+- the entries exampleturtle and examplescreen define the names
+ of these objects as they occur in the docstrings. The
+ transformation of method-docstrings to function-docstrings
+ will delete these names from the docstrings. (See examples in
+ section on HELP)
+- using_IDLE Set this to True if you regularly work with IDLE
+ and it's -n - switch. ("No subprocess") This will prevent
+ exitonclick to enter the mainloop.
+
+There can be a turtle.cfg file in the directory where turtle.py
+is stored and an additional one in the currentworkingdirectory.
+The latter will override the settings of the first one.
-.. _pen-rawpen-objects:
+The turtledemo directory contains a turtle.cfg file. If you
+study it as an example and see its effects when running the
+demos (preferably not from within the demo-viewer).
-Turtle, Pen and RawPen Objects
-------------------------------
+
+VI. Demo scripts
+================
+
+There is a set of demo scripts in the turtledemo directory
+located here ...
-Most of the global functions available in the module are also available as
-methods of the :class:`Turtle`, :class:`Pen` and :class:`RawPen` classes,
-affecting only the state of the given pen.
+ ##### please complete info about path ########################
+
+It contains:
-The only method which is more powerful as a method is :func:`degrees`, which
-takes an optional argument letting you specify the number of units
-corresponding to a full circle:
+- a set of 15 demo scripts demonstrating differet features
+ of the new module turtle.py
+- a Demo-Viewer turtleDemo.py which can be used to view
+ the sourcecode of the scripts and run them at the same time
+ 14 of the examples can be accessed via the Examples Menu.
+ All of them can also be run standalone.
+- The example turtledemo_two_canvases.py demonstrates the
+ simultaneous use of two canvases with the turtle module.
+ Therefor it only can be run standalone.
+- There is a turtle.cfg file in this directory, which also
+ serves as an example for how to write and use such files.
+
+The demoscripts are:
++----------------+------------------------------+-----------------------+
+|Name | description | features |
++----------------+------------------------------+-----------------------+
+|bytedesign | complex classical | tracer, delay |
+| | turtlegraphics pattern | update |
++----------------+------------------------------+-----------------------+
+|chaos | graphs verhust dynamics, | worldcoordinates |
+| | proofs that you must not | |
+| | trust computers computations| |
++----------------+------------------------------+-----------------------+
+|clock | analog clock showing time | turtles as clock's |
+| | of your computer | hands, ontimer |
++----------------+------------------------------+-----------------------+
+|colormixer | experiment with r, g, b | ondrag |
++----------------+------------------------------+-----------------------+
+|fractalcurves | Hilbert & Koch | recursion |
++----------------+------------------------------+-----------------------+
+|lindenmayer | ethnomathematics | L-System |
+| | (indian kolams) | |
++----------------+------------------------------+-----------------------+
+|minimal_hanoi | Towers of Hanoi | Rectangular Turtles |
+| | | as Hanoi-Discs |
+| | | (shape, shapesize) |
++----------------+------------------------------+-----------------------+
+|paint | super minimalistic | onclick |
+| | drawing program | |
++----------------+------------------------------+-----------------------+
+|peace | elementary | turtle: appearance |
+| | | and animation |
++----------------+------------------------------+-----------------------+
+|penrose | aperiodic tiling with | stamp |
+| | kites and darts | |
++----------------+------------------------------+-----------------------+
+|planet_and_moon | simulation of | compound shape |
+| | gravitational system | Vec2D |
++----------------+------------------------------+-----------------------+
+|tree | a (graphical) breadth | clone |
+| | first tree (using generators)| |
++----------------+------------------------------+-----------------------+
+|wikipedia | a pattern from the wikipedia | clone, undo |
+| | article on turtle-graphics | |
++----------------+------------------------------+-----------------------+
+|yingyang | another elementary example | circle |
++----------------+------------------------------+-----------------------+
-.. method:: Turtle.degrees([fullcircle])
+turtledemo_two-canvases: two distinct Tkinter-Canvases
+are populated with turtles. Uses class RawTurtle.
- *fullcircle* is by default 360. This can cause the pen to have any angular units
- whatever: give *fullcircle* ``2*pi`` for radians, or 400 for gradians.
+Have fun!
\ No newline at end of file