turtle --- タートルグラフィックス

ソースコード: Lib/turtle.py

---

はじめに

Turtle graphics is an implementation of the popular geometric drawing tools introduced in Logo, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon in 1967.

Get started

x-y 平面の (0, 0) から動き出すロボット亀を想像してみて下さい。 turtle.forward(15) という命令を出すと、その亀が (スクリーン上で!) 15 ピクセル分顔を向けている方向に動き、動きに沿って線を引きます。 turtle.left(25) という命令を出すと、今度はその場で25度反時計回りに回ります。

Turtle star

Turtle can draw intricate shapes using programs that repeat simple moves.

In Python, turtle graphics provides a representation of a physical "turtle" (a little robot with a pen) that draws on a sheet of paper on the floor.

It's an effective and well-proven way for learners to encounter programming concepts and interaction with software, as it provides instant, visible feedback. It also provides convenient access to graphical output in general.

Turtle drawing was originally created as an educational tool, to be used by teachers in the classroom. For the programmer who needs to produce some graphical output it can be a way to do that without the overhead of introducing more complex or external libraries into their work.

チュートリアル

New users should start here. In this tutorial we'll explore some of the basics of turtle drawing.

Starting a turtle environment

In a Python shell, import all the objects of the turtle module:

from turtle import *

If you run into a No module named '_tkinter' error, you'll have to install the Tk interface package on your system.

Basic drawing

Send the turtle forward 100 steps:

forward(100)

You should see (most likely, in a new window on your display) a line drawn by the turtle, heading East. Change the direction of the turtle, so that it turns 120 degrees left (anti-clockwise):

left(120)

Let's continue by drawing a triangle:

forward(100)
left(120)
forward(100)

Notice how the turtle, represented by an arrow, points in different directions as you steer it.

Experiment with those commands, and also with backward() and right().

Pen の制御

Try changing the color - for example, color('blue') - and width of the line - for example, width(3) - and then drawing again.

You can also move the turtle around without drawing, by lifting up the pen: up() before moving. To start drawing again, use down().

The turtle's position

Send your turtle back to its starting-point (useful if it has disappeared off-screen):

home()

The home position is at the center of the turtle's screen. If you ever need to know them, get the turtle's x-y coordinates with:

pos()

Home is at (0, 0).

And after a while, it will probably help to clear the window so we can start anew:

clearscreen()

Making algorithmic patterns

Using loops, it's possible to build up geometric patterns:

for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)

- which of course, are limited only by the imagination!

Let's draw the star shape at the top of this page. We want red lines, filled in with yellow:

color('red')
fillcolor('yellow')

Just as up() and down() determine whether lines will be drawn, filling can be turned on and off:

begin_fill()

Next we'll create a loop:

while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break

abs(pos()) < 1 is a good way to know when the turtle is back at its home position.

Finally, complete the filling:

end_fill()

(Note that filling only actually takes place when you give the end_fill() command.)

How to...

This section covers some typical turtle use-cases and approaches.

Get started as quickly as possible

One of the joys of turtle graphics is the immediate, visual feedback that's available from simple commands - it's an excellent way to introduce children to programming ideas, with a minimum of overhead (not just children, of course).

The turtle module makes this possible by exposing all its basic functionality as functions, available with from turtle import *. The turtle graphics tutorial covers this approach.

It's worth noting that many of the turtle commands also have even more terse equivalents, such as fd() for forward(). These are especially useful when working with learners for whom typing is not a skill.

You'll need to have the Tk interface package installed on your system for turtle graphics to work. Be warned that this is not always straightforward, so check this in advance if you're planning to use turtle graphics with a learner.

Use the turtle module namespace

Using from turtle import * is convenient - but be warned that it imports a rather large collection of objects, and if you're doing anything but turtle graphics you run the risk of a name conflict (this becomes even more an issue if you're using turtle graphics in a script where other modules might be imported).

The solution is to use import turtle - fd() becomes turtle.fd(), width() becomes turtle.width() and so on. (If typing "turtle" over and over again becomes tedious, use for example import turtle as t instead.)

Use turtle graphics in a script

It's recommended to use the turtle module namespace as described immediately above, for example:

import turtle as t
from random import random

for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

Another step is also required though - as soon as the script ends, Python will also close the turtle's window. Add:

t.mainloop()

to the end of the script. The script will now wait to be dismissed and will not exit until it is terminated, for example by closing the turtle graphics window.

Use object-oriented turtle graphics

参考

Explanation of the object-oriented interface

Other than for very basic introductory purposes, or for trying things out as quickly as possible, it's more usual and much more powerful to use the object-oriented approach to turtle graphics. For example, this allows multiple turtles on screen at once.

In this approach, the various turtle commands are methods of objects (mostly of Turtle objects). You can use the object-oriented approach in the shell, but it would be more typical in a Python script.

The example above then becomes:

from turtle import Turtle
from random import random

t = Turtle()
for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

t.screen.mainloop()

Note the last line. t.screen is an instance of the Screen that a Turtle instance exists on; it's created automatically along with the turtle.

The turtle's screen can be customised, for example:

t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")

Turtle graphics reference

注釈

以下の文書では関数に対する引数リストが与えられています。メソッドでは、勿論、ここでは省略されている self が第一引数になります。

Turtle のメソッド

Turtle の動き

移動および描画

forward() | fd()

backward() | bk() | back()

right() | rt()

left() | lt()

goto() | setpos() | setposition()

teleport()

setx()

sety()

setheading() | seth()

home()

circle()

dot()

stamp()

clearstamp()

clearstamps()

undo()

speed()

Turtle の状態を知る

position() | pos()

towards()

xcor()

ycor()

heading()

distance()

設定と計測

degrees()

radians()

Pen の制御

描画状態

pendown() | pd() | down()

penup() | pu() | up()

pensize() | width()

pen()

isdown()

色の制御

color()

pencolor()

fillcolor()

塗りつぶし

filling()

begin_fill()

end_fill()

さらなる描画の制御

reset()

clear()

write()

タートルの状態

可視性

showturtle() | st()

hideturtle() | ht()

isvisible()

見た目

shape()

resizemode()

shapesize() | turtlesize()

shearfactor()

tiltangle()

tilt()

shapetransform()

get_shapepoly()

イベントを利用する

onclick()

onrelease()

ondrag()

特別な Turtle のメソッド

begin_poly()

end_poly()

get_poly()

clone()

getturtle() | getpen()

getscreen()

setundobuffer()

undobufferentries()

TurtleScreen/Screen のメソッド

ウィンドウの制御

bgcolor()

bgpic()

clearscreen()

resetscreen()

screensize()

setworldcoordinates()

アニメーションの制御

delay()

tracer()

update()

スクリーンイベントを利用する

listen()

onkey() | onkeyrelease()

onkeypress()

onclick() | onscreenclick()

ontimer()

mainloop() | done()

設定と特殊なメソッド

mode()

colormode()

getcanvas()

getshapes()

register_shape() | addshape()

turtles()

window_height()

window_width()

入力メソッド

textinput()

numinput()

Screen 独自のメソッド

bye()

exitonclick()

setup()

title()

RawTurtle/Turtle のメソッドと対応する関数

この節のほとんどの例では turtle という名前の Turtle インスタンスを使います。

Turtle の動き

turtle.forward(distance)

turtle.fd(distance)

パラメータ:

distance -- 数 (整数または浮動小数点数)

タートルが頭を向けている方へ、タートルを距離 distance だけ前進させます。

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)

turtle.back(distance)

turtle.bk(distance)

turtle.backward(distance)

パラメータ:

distance -- 数

タートルが頭を向けている方と反対方向へ、タートルを距離 distance だけ後退させます。 タートルの向きは変えません。

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

turtle.right(angle)

turtle.rt(angle)

パラメータ:

angle -- 数 (整数または浮動小数点数)

タートルを angle 単位だけ右に回します。 (単位のデフォルトは度ですが、 degrees() と radians() 関数を使って設定できます。) 角度の向きはタートルのモードによって意味が変わります。 mode() を参照してください。

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

turtle.left(angle)

turtle.lt(angle)

パラメータ:

angle -- 数 (整数または浮動小数点数)

タートルを angle 単位だけ左に回します。 (単位のデフォルトは度ですが、 degrees() と radians() 関数を使って設定できます。) 角度の向きはタートルのモードによって意味が変わります。 mode() を参照してください。

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

turtle.goto(x, y=None)

turtle.setpos(x, y=None)

turtle.setposition(x, y=None)

パラメータ:

• x -- 数または数のペア/ベクトル

• y -- 数または None

y が None の場合、 x は座標のペアかまたは Vec2D (たとえば pos() で返されます) でなければなりません。

タートルを指定された絶対位置に移動します。ペンが下りていれば線を引きます。タートルの向きは変わりません。

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)

turtle.teleport(x, y=None, *, fill_gap=False)

パラメータ:

• x -- 数または None

• y -- 数または None

• fill_gap -- ブール値

Move turtle to an absolute position. Unlike goto(x, y), a line will not be drawn. The turtle's orientation does not change. If currently filling, the polygon(s) teleported from will be filled after leaving, and filling will begin again after teleporting. This can be disabled with fill_gap=True, which makes the imaginary line traveled during teleporting act as a fill barrier like in goto(x, y).

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.teleport(60)
>>> turtle.pos()
(60.00,0.00)
>>> turtle.teleport(y=10)
>>> turtle.pos()
(60.00,10.00)
>>> turtle.teleport(20, 30)
>>> turtle.pos()
(20.00,30.00)

Added in version 3.12.

turtle.setx(x)

パラメータ:

x -- 数 (整数または浮動小数点数)

タートルの第一座標を x にします。第二座標は変わりません。

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

turtle.sety(y)

パラメータ:

y -- 数 (整数または浮動小数点数)

タートルの第二座標を y にします。第一座標は変わりません。

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

turtle.setheading(to_angle)

turtle.seth(to_angle)

パラメータ:

to_angle -- 数 (整数または浮動小数点数)

タートルの向きを to_angle に設定します。以下はよく使われる方向を度で表わしたものです:

標準モード	logo モード
0 - 東	0 - 北
90 - 北	90 - 東
180 - 西	180 - 南
270 - 南	270 - 西

>>> turtle.setheading(90)
>>> turtle.heading()
90.0

turtle.home()

タートルを原点 -- 座標 (0, 0) -- に移動し、向きを開始方向に設定します (開始方向はモードに依って違います。 mode() を参照してください)。

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

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

パラメータ:

• radius -- 数

• extent -- 数 (または None)

• steps -- 整数 (または None)

半径 radius の円を描きます。中心はタートルの左 radius ユニットの点です。 extent -- 角度です -- は円のどの部分を描くかを決定します。 extent が与えられなければ、デフォルトで完全な円になります。 extent が完全な円でない場合は、弧の一つの端点は、現在のペンの位置です。 radius が正の場合、弧は反時計回りに描かれます。そうでなければ、時計回りです。最後にタートルの向きが extent 分だけ変わります。

円は内接する正多角形で近似されます。 steps でそのために使うステップ数を決定します。この値は与えられなければ自動的に計算されます。また、これを正多角形の描画に利用することもできます。

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

turtle.dot(size=None, *color)

パラメータ:

• size -- 1 以上の整数 (与えられる場合には)

• color -- 色を表わす文字列またはタプル

直径 size の丸い点を color で指定された色で描きます。 size が与えられなかった場合、pensize+4 と 2*pensize の大きい方が使われます。

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

turtle.stamp()

キャンバス上の現在タートルがいる位置にタートルの姿のハンコを押します。そのハンコに対して stamp_id が返されますが、これを使うと後で clearstamp(stamp_id) のように呼び出して消すことができます。

>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)

turtle.clearstamp(stampid)

パラメータ:

stampid -- 整数で、先立つ stamp() 呼出しで返された値でなければなりません

stampid に対応するハンコを消します。

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

turtle.clearstamps(n=None)

パラメータ:

n -- 整数 (または None)

全ての、または最初の/最後の n 個のハンコを消します。 n が None の場合、全てのハンコを消します。 n が正の場合には最初の n 個、 n が負の場合には最後の n 個を消します。

>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()

turtle.undo()

最後の(繰り返すことにより複数の)タートルの動きを取り消します。取り消しできる動きの最大数は undobuffer のサイズによって決まります。

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()

turtle.speed(speed=None)

パラメータ:

speed -- 0 から 10 までの整数またはスピードを表わす文字列(以下の説明を参照)

タートルのスピードを 0 から 10 までの範囲の整数に設定します。引数が与えられない場合は現在のスピードを返します。

与えられた数字が 10 より大きかったり 0.5 より小さかったりした場合は、スピードは 0 になります。スピードを表わす文字列は次のように数字に変換されます:

• "fastest": 0

• "fast": 10

• "normal": 6

• "slow": 3

• "slowest": 1

1 から 10 までのスピードを上げていくにつれて線を描いたりタートルが回ったりするアニメーションがだんだん速くなります。

注意: speed = 0 はアニメーションを無くします。forward/backward ではタートルがジャンプし、left/right では瞬時に方向を変えます。

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

Turtle の状態を知る

turtle.position()

turtle.pos()

タートルの現在位置を (Vec2D のベクトルとして) 返します。

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

turtle.towards(x, y=None)

パラメータ:

• x -- 数または数のペア/ベクトルまたはタートルのインスタンス

• y -- x が数ならば数、そうでなければ None

タートルの位置から指定された (x,y) への直線の角度を返します。この値はタートルの開始方向にそして開始方向はモード ("standard"/"world" または "logo") に依存します。

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

turtle.xcor()

タートルの x 座標を返します。

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

turtle.ycor()

タートルの y 座標を返します。

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

turtle.heading()

タートルの現在の向きを返します (返される値はタートルのモードに依存します。 mode() を参照してください)。

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

turtle.distance(x, y=None)

パラメータ:

• x -- 数または数のペア/ベクトルまたはタートルのインスタンス

• y -- x が数ならば数、そうでなければ None

タートルから与えられた (x,y) あるいはベクトルあるいは渡されたタートルへの距離を、タートルのステップを単位として測った値を返します。

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

設定と計測

turtle.degrees(fullcircle=360.0)

パラメータ:

fullcircle -- 数

角度を計る単位「度」を、円周を何等分するかという値に指定します。デフォルトは360等分で通常の意味での度です。

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

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

turtle.radians()

角度を計る単位をラジアンにします。 degrees(2*math.pi) と同じ意味です。

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

Pen の制御

描画状態

turtle.pendown()

turtle.pd()

turtle.down()

ペンを下ろします -- 動くと線が引かれます。

turtle.penup()

turtle.pu()

turtle.up()

ペンを上げます -- 動いても線は引かれません。

turtle.pensize(width=None)

turtle.width(width=None)

パラメータ:

width -- 正の数

線の太さを width にするか、または現在の太さを返します。resizemode が "auto" でタートルの形が多角形の場合、その多角形も同じ太さで描画されます。引数が渡されなければ、現在の pensize が返されます。

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn

turtle.pen(pen=None, **pendict)

パラメータ:

• pen -- 以下にリストされたキーをもった辞書

• pendict -- 以下にリストされたキーをキーワードとするキーワード引数

ペンの属性を "pen-dictionary" に以下のキー/値ペアで設定するかまたは返します:

• "shown": True/False

• "pendown": True/False

• "pencolor": 色文字列または色タプル

• "fillcolor": 色文字列または色タプル

• "pensize": 正の数

• "speed": 0 から 10 までの整数

• "resizemode": "auto" または "user" または "noresize"

• "stretchfactor": (正の数, 正の数)

• "outline": 正の数

• "tilt": 数

この辞書を以降の pen() 呼出しに渡して以前のペンの状態に復旧することができます。さらに一つ以上の属性をキーワード引数として渡すこともできます。一つの文で幾つものペンの属性を設定するのに使えます。

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]

turtle.isdown()

もしペンが下りていれば True を、上がっていれば False を返します。

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

色の制御

turtle.pencolor(*args)

ペンの色(pencolor)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

pencolor()

現在のペンの色を色指定文字列またはタプルで返します (例を見て下さい)。次の color/pencolor/fillcolor の呼び出しへの入力に使うこともあるでしょう。

pencolor(colorstring)

ペンの色を colorstring に設定します。その値は Tk の色指定文字列で、 "red", "yellow", "#33cc8c" のような文字列です。

pencolor((r, g, b))

ペンの色を r, g, b のタプルで表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。ここで colormode は 1.0 か 255 のどちらかです (colormode() を参照)。

pencolor(r, g, b)

ペンの色を r, g, b で表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。

タートルの形(turtleshape)が多角形の場合、多角形の外側が新しく設定された色で描かれます。

>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)

turtle.fillcolor(*args)

塗りつぶしの色(fillcolor)を設定するかまたは返します。

4種類の入力形式が受け入れ可能です:

fillcolor()

現在の塗りつぶしの色を色指定文字列またはタプルで返します (例を見て下さい)。次の color/pencolor/fillcolor の呼び出しへの入力に使うこともあるでしょう。

fillcolor(colorstring)

塗りつぶしの色を colorstring に設定します。その値は Tk の色指定文字列で、 "red", "yellow", "#33cc8c" のような文字列です。

fillcolor((r, g, b))

塗りつぶしの色を r, g, b のタプルで表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。ここで colormode は 1.0 か 255 のどちらかです (colormode() を参照)。

fillcolor(r, g, b)

塗りつぶしの色を r, g, b で表された RGB の色に設定します。各 r, g, b は 0 から colormode の間の値でなければなりません。

タートルの形(turtleshape)が多角形の場合、多角形の内側が新しく設定された色で描かれます。

>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)

turtle.color(*args)

ペンの色(pencolor)と塗りつぶしの色(fillcolor)を設定するかまたは返します。

いくつかの入力形式が受け入れ可能です。形式ごとに 0 から 3 個の引数を以下のように使います:

color()

現在のペンの色と塗りつぶしの色を pencolor() および fillcolor() で返される色指定文字列またはタプルのペアで返します。

color(colorstring), color((r,g,b)), color(r,g,b)

pencolor() の入力と同じですが、塗りつぶしの色とペンの色、両方を与えられた値に設定します。

color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))

pencolor(colorstring1) および fillcolor(colorstring2) を呼び出すのと等価です。もう一つの入力形式についても同様です。

タートルの形(turtleshape)が多角形の場合、多角形の内側も外側も新しく設定された色で描かれます。

>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

こちらも参照: スクリーンのメソッド colormode() 。

塗りつぶし

turtle.filling()

Return fillstate (True if filling, False else).

>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)

turtle.begin_fill()

To be called just before drawing a shape to be filled.

turtle.end_fill()

最後に呼び出された begin_fill() の後に描かれた図形を塗りつぶします。

Whether or not overlap regions for self-intersecting polygons or multiple shapes are filled depends on the operating system graphics, type of overlap, and number of overlaps. For example, the Turtle star above may be either all yellow or have some white regions.

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

さらなる描画の制御

turtle.reset()

タートルの描いたものをスクリーンから消し、タートルを中心に戻して、全ての変数をデフォルト値に設定し直します。

>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.clear()

タートルの描いたものをスクリーンから消します。タートルは動かしません。タートルの状態と位置、それに他のタートルたちの描いたものは影響を受けません。

turtle.write(arg, move=False, align='left', font=('Arial', 8, 'normal'))

パラメータ:

• arg -- TurtleScreen に書かれるオブジェクト

• move -- True/False

• align -- 文字列 "left", "center", right" のどれか

• font -- 三つ組み (fontname, fontsize, fonttype)

文字を書きます— arg の文字列表現を、現在のタートルの位置に、 align ("left", "center", "right" のどれか) に従って、 与えられたフォントで。 もし move が真ならば、ペンは書いた文の右下隅に移動します。 デフォルトでは、 move は False です。

>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)

タートルの状態

可視性

turtle.hideturtle()

turtle.ht()

タートルを見えなくします。 複雑な図を描いている途中、タートルが見えないようにするのは良い考えです。 というのもタートルを隠すことで描画が目に見えて速くなるからです。

>>> turtle.hideturtle()

turtle.showturtle()

turtle.st()

タートルが見えるようにします。

>>> turtle.showturtle()

turtle.isvisible()

タートルが見えている状態ならば True を、隠されていれば False を返します。

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

見た目

turtle.shape(name=None)

パラメータ:

name -- 形の名前(shapename)として正しい文字列

タートルの形を与えられた名前(name)の形に設定するか、もしくは名前が与えられなければ現在の形の名前を返します。 name という名前の形は TurtleScreen の形の辞書に載っていなければなりません。最初は次の多角形が載っています: "arrow", "turtle", "circle", "square", "triangle", "classic"。形についての扱いを学ぶには Screen のメソッド register_shape() を参照して下さい。

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'

turtle.resizemode(rmode=None)

パラメータ:

rmode -- 文字列 "auto", "user", "noresize" のどれか

サイズ変更のモード(resizemode)を "auto", "user", "noresize" のどれかに設定します。もし rmode が与えられなければ、現在のサイズ変更モードを返します。それぞれのサイズ変更モードは以下の効果を持ちます:

• "auto": ペンのサイズに対応してタートルの見た目を調整します。

• "user": 伸長係数(stretchfactor)およびアウトライン幅(outlinewidth)の値に対応してタートルの見た目を調整します。これらの値は shapesize() で設定します。

• "noresize": タートルの見た目を調整しません。

resizemode("user") は shapesize() に引数を渡したときに呼び出されます。

>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'

turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)

turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)

パラメータ:

• stretch_wid -- 正の数

• stretch_len -- 正の数

• outline -- 正の数

ペンの属性 x/y-伸長係数および/またはアウトラインを返すかまたは設定します。サイズ変更のモードは "user" に設定されます。サイズ変更のモードが "user" に設定されたときかつそのときに限り、タートルは伸長係数(stretchfactor)に従って伸長されて表示されます。 stretch_wid は進行方向に直交する向きの伸長係数で、 stretch_len は進行方向に沿ったの伸長係数、 outline は形のアウトラインの幅を決めるものです。

>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)

turtle.shearfactor(shear=None)

パラメータ:

shear -- number (optional)

Set or return the current shearfactor. Shear the turtleshape according to the given shearfactor shear, which is the tangent of the shear angle. Do not change the turtle's heading (direction of movement). If shear is not given: return the current shearfactor, i. e. the tangent of the shear angle, by which lines parallel to the heading of the turtle are sheared.

>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5

turtle.tilt(angle)

パラメータ:

angle -- 数

タートルの形(turtleshape)を現在の傾斜角から角度(angle)だけ回転します。このときタートルの進む方向は 変わりません 。

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)

turtle.tiltangle(angle=None)

パラメータ:

angle -- a number (optional)

Set or return the current tilt-angle. If angle is given, 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). If angle is not given: return the current tilt-angle, i. e. the angle between the orientation of the turtleshape and the heading of the turtle (its direction of movement).

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0

turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)

パラメータ:

• t11 -- a number (optional)

• t12 -- a number (optional)

• t21 -- a number (optional)

• t12 -- a number (optional)

Set or return the current transformation matrix of the turtle shape.

If none of the matrix elements are given, return the transformation matrix as a tuple of 4 elements. Otherwise set the given elements and transform the turtleshape according to the matrix consisting of first row t11, t12 and second row t21, t22. The determinant t11 * t22 - t12 * t21 must not be zero, otherwise an error is raised. Modify stretchfactor, shearfactor and tiltangle according to the given matrix.

>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)

turtle.get_shapepoly()

Return the current shape polygon as tuple of coordinate pairs. This can be used to define a new shape or components of a compound shape.

>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))

イベントを利用する

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

パラメータ:

• fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

• btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

• add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスクリック(mouse-click)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。無名タートル、つまり手続き的なやり方の例です:

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

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

パラメータ:

• fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

• btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

• add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスボタンリリース(mouse-button-release)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

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

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

パラメータ:

• fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

• btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

• add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスムーブ(mouse-move)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

注意: 全てのマウスムーブイベントのシーケンスに先立ってマウスクリックイベントが起こります。

>>> turtle.ondrag(turtle.goto)

この後、タートルをクリックしてドラッグするとタートルはスクリーン上を動きそれによって(ペンが下りていれば)手書きの線ができあがります。

特別な Turtle のメソッド

turtle.begin_poly()

多角形の頂点の記録を開始します。現在のタートル位置が最初の頂点です。

turtle.end_poly()

多角形の頂点の記録を停止します。現在のタートル位置が最後の頂点です。この頂点が最初の頂点と結ばれます。

turtle.get_poly()

最後に記録された多角形を返します。

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

turtle.clone()

位置、向きその他のプロパティがそっくり同じタートルのクローンを作って返します。

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

turtle.getturtle()

turtle.getpen()

Turtle オブジェクトそのものを返します。唯一の意味のある使い方: 無名タートルを返す関数として使う:

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

turtle.getscreen()

タートルが描画中の TurtleScreen オブジェクトを返します。 TurtleScreen のメソッドをそのオブジェクトに対して呼び出すことができます。

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

turtle.setundobuffer(size)

パラメータ:

size -- 整数または None

アンドゥバッファを設定または無効化します。 size が整数ならばそのサイズの空のアンドゥバッファを用意します。 size の値はタートルのアクションを何度 undo() メソッド/関数で取り消せるかの最大数を与えます。 size が None ならば、アンドゥバッファは無効化されます。

>>> turtle.setundobuffer(42)

turtle.undobufferentries()

アンドゥバッファのエントリー数を返します。

>>> while undobufferentries():
...     undo()

Compound shapes

合成されたタートルの形、つまり幾つかの色の違う多角形から成るような形を使うには、以下のように補助クラス Shape を直接使わなければなりません:

1. タイプ "compound" の空の Shape オブジェクトを作ります。

2. addcomponent() メソッドを使って、好きなだけここにコンポーネントを追加します。

   例えば:

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

3. こうして作った Shape を Screen の形のリスト(shapelist) に追加して使います:

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

注釈

Shape クラスは register_shape() の内部では違った使われ方をします。アプリケーションを書く人が Shape クラスを扱わなければならないのは、上で示したように合成された形を使うとき だけ です！

TurtleScreen/Screen のメソッドと対応する関数

この節のほとんどの例では screen という名前の TurtleScreen インスタンスを使います。

ウィンドウの制御

turtle.bgcolor(*args)

パラメータ:

args -- 色文字列または 0 から colormode の範囲の数3つ、 またはそれを三つ組みにしたもの

TurtleScreen の背景色を設定するかまたは返します。

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

turtle.bgpic(picname=None)

パラメータ:

picname -- 文字列で gif ファイルの名前 "nopic" 、または None

背景の画像を設定するかまたは現在の背景画像(backgroundimage)の名前を返します。 picname がファイル名ならば、その画像を背景に設定します。 picname が "nopic" ならば、(もしあれば)背景画像を削除します。 picname が None ならば、現在の背景画像のファイル名を返します。

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

turtle.clear()

注釈

この TurtleScreen メソッドはグローバル関数としては clearscreen という名前でだけ使えます。グローバル関数 clear は Turtle メソッドの clear から派生した別ものです。

turtle.clearscreen()

全ての図形と全てのタートルを TurtleScreen から削除します。そして空になった TurtleScreen をリセットして初期状態に戻します: 白い背景、背景画像もイベント束縛もなく、トレーシングはオンです。

turtle.reset()

注釈

この TurtleScreen メソッドはグローバル関数としては resetscreen という名前でだけ使えます。グローバル関数 reset は Turtle メソッドの reset から派生した別ものです。

turtle.resetscreen()

スクリーン上の全てのタートルをリセットしその初期状態に戻します。

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

パラメータ:

• canvwidth -- 正の整数でピクセル単位の新しいキャンバス幅(canvaswidth)

• canvheight -- 正の整数でピクセル単位の新しいキャンバス高さ(canvasheight)

• bg -- 色文字列または色タプルで新しい背景色

引数が渡されなければ、現在の (キャンバス幅, キャンバス高さ) を返します。そうでなければタートルが描画するキャンバスのサイズを変更します。描画ウィンドウには影響しません。キャンバスの隠れた部分を見るためにはスクロールバーを使って下さい。このメソッドを使うと、以前はキャンバスの外にあったそうした図形の一部を見えるようにすることができます。

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

# 逃げ出してしまったタートルを探すためとかね ;-)

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

パラメータ:

• llx -- 数でキャンバスの左下隅の x-座標

• lly -- 数でキャンバスの左下隅の y-座標

• urx -- 数でキャンバスの右上隅の x-座標

• ury -- 数でキャンバスの右上隅の y-座標

ユーザー定義座標系を準備し必要ならばモードを "world" に切り替えます。この動作は screen.reset() を伴います。すでに "world" モードになっていた場合、全ての図形は新しい座標に従って再描画されます。

重要なお知らせ: ユーザー定義座標系では角度が歪むかもしれません。

>>> 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 octagon

アニメーションの制御

turtle.delay(delay=None)

パラメータ:

delay -- 正の整数

描画の遅延(delay)をミリ秒単位で設定するかまたはその値を返します。(これは概ね引き続くキャンバス更新の時間間隔です。) 遅延が大きくなると、アニメーションは遅くなります。

オプション引数:

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

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

パラメータ:

• n -- 非負整数

• delay -- 非負整数

タートルのアニメーションをオン・オフし、描画更新の遅延を設定します。 n が与えられた場合、通常のスクリーン更新のうち 1/n しか実際に実行されません。 (複雑なグラフィックスの描画を加速するのに使えます。) 引数なしで呼び出されたなら、現在保存されている n の値を返します。二つ目の引数は遅延の値を設定します(delay() も参照)。

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

turtle.update()

TurtleScreen の更新を実行します。トレーサーがオフの時に使われます。

RawTurtle/Turtle のメソッド speed() も参照して下さい。

スクリーンイベントを利用する

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

TurtleScreen に(キー・イベントを収集するために)フォーカスします。ダミー引数は listen() を onclick メソッドに渡せるようにするためのものです。

turtle.onkey(fun, key)

turtle.onkeyrelease(fun, key)

パラメータ:

• fun -- 引数なしの関数または None

• key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

fun を指定されたキーのキーリリース(key-release)イベントに束縛します。 fun が None ならばイベント束縛は除かれます。注意: キー・イベントを登録できるようにするためには TurtleScreen はフォーカスを持っていないとなりません(listen() を参照)。

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

turtle.onkeypress(fun, key=None)

パラメータ:

• fun -- 引数なしの関数または None

• key -- 文字列: キー (例 "a") またはキー・シンボル (例 "space")

Bind fun to key-press event of key if key is given, or to any key-press-event if no key is given. Remark: in order to be able to register key-events, TurtleScreen must have focus. (See method listen().)

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

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

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

パラメータ:

• fun -- 2引数の関数でキャンバスのクリックされた点の座標を引数として呼び出されるものです

• btn -- マウスボタンの番号、デフォルトは 1 (左マウスボタン)

• add -- True または False -- True ならば、 新しい束縛が追加されますが、そうでなければ、 以前の束縛を置き換えます。

fun をタートルのマウスクリック(mouse-click)イベントに束縛します。 fun が None ならば、既存の束縛が取り除かれます。

Example for a screen という名の TurtleScreen インスタンスと turtle という名前の Turtle インスタンスの例:

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

注釈

この TurtleScreen メソッドはグローバル関数としては onscreenclick という名前でだけ使えます。グローバル関数 onclick は Turtle メソッドの onclick から派生した別ものです。

turtle.ontimer(fun, t=0)

パラメータ:

• fun -- 引数なし関数

• t -- 数 >= 0

t ミリ秒後に fun を呼び出すタイマーを仕掛けます。

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

turtle.mainloop()

turtle.done()

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

>>> screen.mainloop()

入力メソッド

turtle.textinput(title, prompt)

パラメータ:

• title -- string

• prompt -- string

Pop up a dialog window for input of a string. Parameter title is the title of the dialog window, prompt is a text mostly describing what information to input. Return the string input. If the dialog is canceled, return None.

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

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

パラメータ:

• title -- string

• prompt -- string

• default -- number (optional)

• minval -- number (optional)

• maxval -- number (optional)

Pop up a dialog window for input of a number. title is the title of the dialog window, prompt is a text mostly describing what numerical information to input. default: default value, minval: minimum value for input, maxval: maximum value for input. The number input must be in the range minval .. maxval if these are given. If not, a hint is issued and the dialog remains open for correction. Return the number input. If the dialog is canceled, return None.

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

設定と特殊なメソッド

turtle.mode(mode=None)

パラメータ:

mode -- 文字列 "standard", "logo", "world" のいずれか

タートルのモード("standard", "logo", "world" のいずれか)を設定してリセットします。モードが渡されなければ現在のモードが返されます。

モード "standard" は古い turtle 互換です。モード "logo" は Logo タートルグラフィックスとほぼ互換です。モード "world" はユーザーの定義した「世界座標(world coordinates)」を使います。 重要なお知らせ: このモードでは x/y 比が 1 でないと角度が歪むかもしれません。

モード	タートルの向きの初期値	正の角度
"standard"	右 (東) 向き	反時計回り
"logo"	上 (北) 向き	時計回り

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

turtle.colormode(cmode=None)

パラメータ:

cmode -- 1.0 か 255 のどちらかの値

色モード(colormode)を返すか、または 1.0 か 255 のどちらかの値に設定します。設定した後は、色トリプルの r, g, b 値は 0 から cmode の範囲になければなりません。

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

turtle.getcanvas()

この TurtleScreen の Canvas を返します。Tkinter の Canvas を使って何をするか知っている人には有用です。

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

turtle.getshapes()

現在使うことのできる全てのタートルの形のリストを返します。

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

turtle.register_shape(name, shape=None)

turtle.addshape(name, shape=None)

この関数を呼び出す三つの異なる方法があります:

1. name が gif ファイルの名前で shape が None: 対応する画像の形を取り込みます。

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

   注釈

   画像の形はタートルが向きを変えても 回転しません ので、タートルがどちらを向いているか見ても判りません!

2. name が任意の文字列で shape が座標ペアのタプル: 対応する多角形を取り込みます。

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

3. name が任意の文字列で shape が (合成形の) Shape オブジェクト: 対応する合成形を取り込みます。

タートルの形を TurtleScreen の形リスト(shapelist)に加えます。このように登録された形だけが shape(shapename) コマンドに使えます。

turtle.turtles()

スクリーン上のタートルのリストを返します。

>>> for turtle in screen.turtles():
...     turtle.color("red")

turtle.window_height()

タートルウィンドウの高さを返します。

>>> screen.window_height()
480

turtle.window_width()

タートルウィンドウの幅を返します。

>>> screen.window_width()
640

Screen 独自のメソッド、TurtleScreen から継承したもの以外

turtle.bye()

タートルグラフィックス(turtlegraphics)のウィンドウを閉じます。

turtle.exitonclick()

スクリーン上のマウスクリックに bye() メソッドを束縛します。

設定辞書中の "using_IDLE" の値が False (デフォルトです) の場合、さらにメインループ(mainloop)に入ります。注意: もし IDLE が -n スイッチ(サブプロセスなし)付きで使われているときは、この値は turtle.cfg の中で True とされているべきです。この場合、IDLE のメインループもクライアントスクリプトから見てアクティブです。

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

メインウィンドウのサイズとポジションを設定します。引数のデフォルト値は設定辞書に収められており、 turtle.cfg ファイルを通じて変更できます。

パラメータ:

• width -- 整数ならばピクセル単位のサイズ、浮動小数点数ならばスクリーンに対する割合 (スクリーンの 50% がデフォルト)

• height -- 整数ならばピクセル単位の高さ、浮動小数点数ならばスクリーンに対する割合 (スクリーンの 75% がデフォルト)

• startx -- 正の数ならばスクリーンの左端からピクセル単位で測った開始位置、 負の数ならば右端から、None ならば水平方向に真ん中

• starty -- 正の数ならばスクリーンの上端からピクセル単位で測った開始位置、 負の数ならば下端から、None ならば垂直方向に真ん中

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

turtle.title(titlestring)

パラメータ:

titlestring -- タートルグラフィックスウィンドウのタイトルバーに表示される文字列

ウインドウのタイトルを titlestring に設定します。

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

Public classes

class turtle.RawTurtle(canvas)

class turtle.RawPen(canvas)

パラメータ:

canvas -- a tkinter.Canvas, a ScrolledCanvas or a TurtleScreen

タートルを作ります。タートルには上の「Turtle/RawTurtle のメソッド」で説明した全てのメソッドがあります。

class turtle.Turtle

RawTurtle のサブクラスで同じインターフェイスを持ちますが、最初に必要になったとき自動的に作られる Screen オブジェクトに描画します。

class turtle.TurtleScreen(cv)

パラメータ:

cv -- a tkinter.Canvas

上で説明した bgcolor() のようなスクリーン向けのメソッドを提供します。

class turtle.Screen

TurtleScreen のサブクラスで 4つのメソッドが加わっています 。

class turtle.ScrolledCanvas(master)

パラメータ:

master -- この ScrolledCanvas すなわちスクロールバーの付いた Tkinter canvas を収める Tkinter ウィジェット

タートルたちが遊び回る場所として自動的に ScrolledCanvas を提供する Screen クラスによって使われます。

class turtle.Shape(type_, data)

パラメータ:

type_ -- 文字列 "polygon", "image", "compound" のいずれか

形をモデル化するデータ構造。ペア (type_, data) は以下の仕様に従わなければなりません:

type_	data
"polygon"	多角形タプル、すなわち座標ペアのタプル
"image"	画像 (この形式は内部的にのみ使用されます!)
"compound"	None (合成形は addcomponent() メソッドを使って作らなければなりません)

addcomponent(poly, fill, outline=None)

パラメータ:

• poly -- 多角形、すなわち数のペアのタプル

• fill -- poly を塗りつぶす色

• outline -- poly のアウトラインの色 (与えられた場合)

例:

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

Compound shapes を参照。

class turtle.Vec2D(x, y)

2次元ベクトルのクラスで、タートルグラフィックスを実装するための補助クラス。タートルグラフィックスを使ったプログラムでも有用でしょう。タプルから派生しているので、ベクターはタプルです!

以下の演算が使えます (a, b はベクトル、 k は数):

• a + b ベクトル和

• a - b ベクトル差

• a * b 内積

• k * a および a * k スカラー倍

• abs(a) a の絶対値

• a.rotate(angle) 回転

説明

A turtle object draws on a screen object, and there a number of key classes in the turtle object-oriented interface that can be used to create them and relate them to each other.

A Turtle instance will automatically create a Screen instance if one is not already present.

Turtle is a subclass of RawTurtle, which doesn't automatically create a drawing surface - a canvas will need to be provided or created for it. The canvas can be a tkinter.Canvas, ScrolledCanvas or TurtleScreen.

TurtleScreen is the basic drawing surface for a turtle. Screen is a subclass of TurtleScreen, and includes some additional methods for managing its appearance (including size and title) and behaviour. TurtleScreen's constructor needs a tkinter.Canvas or a ScrolledCanvas as an argument.

The functional interface for turtle graphics uses the various methods of Turtle and TurtleScreen/Screen. Behind the scenes, a screen object is automatically created whenever a function derived from a Screen method is called. Similarly, a turtle object is automatically created whenever any of the functions derived from a Turtle method is called.

To use multiple turtles on a screen, the object-oriented interface must be used.

ヘルプと設定

ヘルプの使い方

Screen と Turtle クラスのパブリックメソッドはドキュメント文字列で網羅的に文書化されていますので、Python のヘルプ機能を通じてオンラインヘルプとして利用できます:

• IDLE を使っているときは、打ち込んだ関数/メソッド呼び出しのシグニチャとドキュメント文字列の一行目がツールチップとして表示されます。

• help() をメソッドや関数に対して呼び出すとドキュメント文字列が表示されます:

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

• メソッドに由来する関数のドキュメント文字列は変更された形をとります:

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

これらの変更されたドキュメント文字列はインポート時にメソッドから導出される関数定義と一緒に自動的に作られます。

ドキュメント文字列の翻訳

Screen と Turtle クラスのパブリックメソッドについて、キーがメソッド名で値がドキュメント文字列である辞書を作るユーティリティがあります。

turtle.write_docstringdict(filename='turtle_docstringdict')

パラメータ:

filename -- ファイル名として使われる文字列

ドキュメント文字列辞書(docstring-dictionary)を作って与えられたファイル名の Python スクリプトに書き込みます。この関数はわざわざ呼び出さなければなりません (タートルグラフィックスのクラスから使われることはありません)。ドキュメント文字列辞書は filename.py という Python スクリプトに書き込まれます。ドキュメント文字列の異なった言語への翻訳に対するテンプレートとして使われることを意図したものです。

もしあなたが(またはあなたの生徒さんが) turtle を自国語のオンラインヘルプ付きで使いたいならば、ドキュメント文字列を翻訳してできあがったファイルをたとえば turtle_docstringdict_german.py という名前で保存しなければなりません。

さらに turtle.cfg ファイルで適切な設定をしておけば、このファイルがインポート時に読み込まれて元の英語のドキュメント文字列を置き換えます。

この文書を書いている時点ではドイツ語とイタリア語のドキュメント文字列辞書が存在します。 ( glingl@aon.at にリクエストして下さい。)

Screen および Turtle の設定方法

初期デフォルト設定では古い turtle の見た目と振る舞いを真似るようにして、互換性を最大限に保つようにしています。

このモジュールの特性を反映した、あるいは個々人の必要性 (たとえばクラスルームでの使用)に合致した、異なった設定を使いたい場合、設定ファイル turtle.cfg を用意してインポート時に読み込ませその設定に従わせることができます。

初期設定は以下の 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

いくつかピックアップしたエントリーの短い説明:

• 最初の4行は Screen.setup メソッドの引数に当たります。

• 5行目6行目は Screen.screensize メソッドの引数に当たります。

• shape は最初から用意されている形ならどれでも使えます(arrow, turtle など)。詳しくは help(shape) をお試し下さい。

• 塗りつぶしの色(fill color)を使いたくない(つまりタートルを透明にしたい)場合、 fillcolor = "" と書かなければなりません (しかし全ての空でない文字列は cfg ファイル中で引用符を付けてはいけません)。

• タートルにその状態を反映させるためには resizemode = auto とします。

• たとえば language = italian とするとドキュメント文字列辞書(docstringdict) として turtle_docstringdict_italian.py がインポート時に読み込まれます (もしそれがインポートパス、たとえば turtle と同じディレクトリにあれば)。

• exampleturtle および examplescreen はこれらのオブジェクトのドキュメント文字列内での呼び名を決めます。メソッドのドキュメント文字列から関数のドキュメント文字列に変換する際に、これらの名前は取り除かれます。

• using_IDLE: IDLE とその -n スイッチ(サブプロセスなし)を常用するならば、この値を True に設定して下さい。これにより exitonclick() がメインループ(mainloop)に入るのを阻止します。

turtle.cfg ファイルは turtle の保存されているディレクトリと現在の作業ディレクトリに追加的に存在し得ます。後者が前者の設定をオーバーライドします。

Lib/turtledemo ディレクトリにも turtle.cfg ファイルがあります。 デモを実際に(できればデモビュワーからでなく)実行してそこに書かれたものとその効果を学びましょう。

turtledemo --- デモスクリプト

turtledemo パッケージには一連のデモスクリプトが含まれています。これらのスクリプトは以下のように、付属のデモビューアを使用して実行および表示できます:

python -m turtledemo

あるいは、個別にデモスクリプトを実行できます。たとえば 、:

python -m turtledemo.bytedesign

turtledemo パッケージのディレクトリには次のものが含まれます:

• ソースコードを眺めつつスクリプトを実行できるデモビュワー __main__.py 。

• Multiple scripts demonstrating different features of the turtle module. Examples can be accessed via the Examples menu. They can also be run standalone.

• 設定ファイルの書き方や使い方の例として参考にできる turtle.cfg ファイル。

デモスクリプトは以下の通りです:

名前	説明	フィーチャー
bytedesign	複雑な古典的タートルグラフィックスパターン	tracer(), delay, update()
chaos	verhust 力学系のグラフ化, コンピュータの計算が常識的な予想に反する場合があることを示します。	世界座標系
clock	コンピュータの時間を示すアナログ時計	タートルが時計の針, ontimer
colormixer	r, g, b の実験	ondrag()
forest	3 breadth-first trees	randomization
fractalcurves	Hilbert & Koch 曲線	再帰
lindenmayer	民俗的数学 (インド kolams)	L-システム
minimal_hanoi	ハノイの塔	ハノイ盤として正方形のタートル (shape, shapesize)
nim	play the classical nim game with three heaps of sticks against the computer.	turtles as nimsticks, event driven (mouse, keyboard)
paint	超極小主義的描画プログラム	onclick()
peace	初歩的	turtle: 見た目とアニメーション
penrose	凧と矢による非周期的タイリング	stamp()
planet_and_moon	重力系のシミュレーション	合成形, Vec2D
rosette	タートルグラフィックスについての wikipedia の記事の例	clone(), undo()
round_dance	dancing turtles rotating pairwise in opposite direction	compound shapes, clone shapesize, tilt, get_shapepoly, update
sorting_animate	visual demonstration of different sorting methods	simple alignment, randomization
tree	(図形的) 幅優先木 (ジェネレータを使って)	clone()
two_canvases	simple design	turtles on two canvases
yinyang	もう一つの初歩的な例	circle()

楽しんでね!

python 2.6からの変更点

• The methods Turtle.tracer, Turtle.window_width and Turtle.window_height have been eliminated. Methods with these names and functionality are now available only as methods of Screen. The functions derived from these remain available. (In fact already in Python 2.6 these methods were merely duplications of the corresponding TurtleScreen/Screen methods.)

• The method Turtle.fill() has been eliminated. The behaviour of begin_fill() and end_fill() have changed slightly: now every filling process must be completed with an end_fill() call.

• A method Turtle.filling has been added. It returns a boolean value: True if a filling process is under way, False otherwise. This behaviour corresponds to a fill() call without arguments in Python 2.6.

python 3.0からの変更点

• The Turtle methods shearfactor(), shapetransform() and get_shapepoly() have been added. Thus the full range of regular linear transforms is now available for transforming turtle shapes. tiltangle() has been enhanced in functionality: it now can be used to get or set the tilt angle.

• The Screen method onkeypress() has been added as a complement to onkey(). As the latter binds actions to the key release event, an alias: onkeyrelease() was also added for it.

• The method Screen.mainloop has been added, so there is no longer a need to use the standalone mainloop() function when working with Screen and Turtle objects.

• Two input methods have been added: Screen.textinput and Screen.numinput. These pop up input dialogs and return strings and numbers respectively.

• Two example scripts tdemo_nim.py and tdemo_round_dance.py have been added to the Lib/turtledemo directory.