mirror of https://github.com/python/cpython.git
2002 lines
66 KiB
ReStructuredText
2002 lines
66 KiB
ReStructuredText
========================================
|
|
:mod:`turtle` --- Turtle graphics for Tk
|
|
========================================
|
|
|
|
------------
|
|
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)
|
|
|
|
|
|
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:
|
|
|
|
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::
|
|
|
|
>>> 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")
|
|
|
|
Now add Shape s to the Screen's shapelist ...
|
|
.. and use it::
|
|
|
|
>>> register_shape("myshape", s)
|
|
>>> shape("myshape")
|
|
|
|
|
|
NOTE 1: addcomponent() is a method of class Shape (not of
|
|
Turtle nor Screen) and thus there is NO FUNCTION of the same name.
|
|
|
|
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!
|
|
|
|
NOTE 3: A short description of the class Shape is in section 4.
|
|
|
|
|
|
|
|
3. METHODS OF TurtleScreen/Screen AND CORRESPONDING FUNCTIONS
|
|
=============================================================
|
|
|
|
|
|
WINDOW CONTROL
|
|
--------------
|
|
|
|
|
|
.. method:: bgcolor(*args)
|
|
args -- a color string or three numbers in the range 0..colormode
|
|
or a 3-tuple of such numbers.
|
|
|
|
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'
|
|
|
|
|
|
.. 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'
|
|
|
|
|
|
.. 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.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
screen.clear()
|
|
|
|
*Note*: this method is only available as the function named
|
|
clearscreen(). (The function clear() is another one derived from
|
|
the Turtle-method clear()!).
|
|
|
|
|
|
.. method:: reset()
|
|
.. method:: resetscreen()
|
|
Reset all Turtles on the Screen to their initial state.
|
|
|
|
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()!).
|
|
|
|
|
|
.. 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
|
|
|
|
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.
|
|
|
|
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
|
|
-----------------
|
|
|
|
|
|
.. 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)::
|
|
|
|
>>> screen.delay(15)
|
|
>>> screen.delay()
|
|
15
|
|
|
|
|
|
.. 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())
|
|
|
|
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()
|
|
|
|
|
|
USING SCREEN EVENTS
|
|
-------------------
|
|
|
|
|
|
.. 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.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
>>> screen.listen()
|
|
|
|
|
|
.. 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.)
|
|
|
|
Example (for a TurtleScreen instance named screen
|
|
and a Turtle instance named turtle)::
|
|
|
|
>>> 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)::
|
|
|
|
>>> 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
|
|
|
|
*Note*: this method is only available as the function named
|
|
onscreenclick(). (The function onclick() is a different one derived
|
|
from the Turtle-method onclick()!).
|
|
|
|
|
|
.. method:: ontimer(fun, t=0):
|
|
fun -- a function with no arguments.
|
|
t -- a number >= 0
|
|
|
|
Install a timer, which calls fun after t milliseconds.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
|
|
>>> running = True
|
|
>>> def f():
|
|
if running:
|
|
fd(50)
|
|
lt(60)
|
|
screen.ontimer(f, 250)
|
|
>>> f() ### makes the turtle marching around
|
|
>>> running = False
|
|
|
|
|
|
SETTINGS AND SPECIAL METHODS
|
|
|
|
|
|
.. 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.
|
|
|
|
============ ========================= ===================
|
|
Mode Initial turtle heading positive angles
|
|
============ ========================= ===================
|
|
'standard' to the right (east) counterclockwise
|
|
'logo' upward (north) clockwise
|
|
============ ========================= ===================
|
|
|
|
Examples::
|
|
>>> mode('logo') # resets turtle heading to north
|
|
>>> mode()
|
|
'logo'
|
|
|
|
|
|
.. method:: colormode(cmode=None):
|
|
cmode -- one of the values 1.0 or 255
|
|
|
|
"""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)
|
|
|
|
|
|
.. 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>
|
|
|
|
|
|
.. 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']
|
|
|
|
|
|
.. 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).
|
|
|
|
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)))
|
|
|
|
|
|
.. method:: turtles():
|
|
Return the list of turtles on the screen.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
>>> for turtle in screen.turtles()
|
|
... turtle.color("red")
|
|
|
|
|
|
.. method:: window_height():
|
|
Return the height of the turtle window.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
>>> screen.window_height()
|
|
480
|
|
|
|
|
|
.. method:: window_width():
|
|
Return the width of the turtle window.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
>>> screen.window_width()
|
|
640
|
|
|
|
|
|
METHODS SPECIFIC TO Screen, not inherited from TurtleScreen
|
|
-----------------------------------------------------------
|
|
|
|
|
|
.. method:: bye():
|
|
"""Shut the turtlegraphics window.
|
|
|
|
This is a method of the Screen-class and not available for
|
|
TurtleScreen instances.
|
|
|
|
Example (for a TurtleScreen instance named screen):
|
|
>>> screen.bye()
|
|
|
|
|
|
.. 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.
|
|
|
|
This is a method of the Screen-class and not available for
|
|
TurtleScreen instances.
|
|
|
|
Example (for a Screen instance named screen):
|
|
>>> screen.exitonclick()
|
|
|
|
|
|
.. 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.
|
|
|
|
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
|
|
|
|
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
|
|
# sets window to 75% of screen by 50% of screen and centers
|
|
|
|
|
|
.. method:: title(titlestring):
|
|
titlestring -- a string, to appear in the titlebar of the
|
|
turtle graphics window.
|
|
|
|
Set title of turtle-window to titlestring
|
|
|
|
This is a method of the Screen-class and not available for
|
|
TurtleScreen instances.
|
|
|
|
Example (for a Screen instance named screen):
|
|
>>> screen.title("Welcome to the turtle-zoo!")
|
|
|
|
|
|
|
|
4. THE PUBLIC CLASSES of the module turtle.py
|
|
=============================================
|
|
|
|
|
|
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.
|
|
|
|
class Shape(type\_, data)
|
|
type --- one of the strings "polygon", "image", "compound"
|
|
|
|
Data structure modeling shapes.
|
|
The pair type\_, data must be as follows:
|
|
|
|
type\_ data
|
|
|
|
"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
|
|
|
|
|
|
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!
|
|
|
|
Provides (for a, b vectors, k number):
|
|
|
|
* 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
|
|
|
|
|
|
|
|
V. HELP AND CONFIGURATION
|
|
=========================
|
|
|
|
This section contains subsections on:
|
|
|
|
- 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
|
|
|
|
|
|
HOW TO USE HELP:
|
|
----------------
|
|
|
|
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:
|
|
|
|
- When using IDLE, tooltips show the signatures and first lines of
|
|
the docstrings of typed in function-/method calls.
|
|
|
|
- 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::
|
|
|
|
>>> 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
|
|
function definitions 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 names and the values of which are the docstrings of the public
|
|
methods of the classes Screen and Turtle.
|
|
|
|
write_docstringdict(filename="turtle_docstringdict"):
|
|
filename -- a string, used as filename
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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
|
|
-----------------------------------
|
|
|
|
The built-in default configuration mimics the appearance and
|
|
behaviour of the old turtle module in order to retain best possible
|
|
compatibility with it.
|
|
|
|
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:
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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).
|
|
|
|
|
|
VI. Demo scripts
|
|
================
|
|
|
|
There is a set of demo scripts in the turtledemo directory
|
|
located here ...
|
|
|
|
##### please complete info about path ########################
|
|
|
|
It contains:
|
|
|
|
- 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 |
|
|
+----------------+------------------------------+-----------------------+
|
|
|
|
turtledemo_two-canvases: two distinct Tkinter-Canvases
|
|
are populated with turtles. Uses class RawTurtle.
|
|
|
|
|
|
Have fun! |