# `turtle` --- Turtle graphics

ソースコード: 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度反時計回りに回ります。

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.

### Automatically begin and end filling

Starting with Python 3.14, you can use the `fill()` context manager instead of `begin_fill()` and `end_fill()` to automatically begin and end fill. Here is an example:

    with fill():
        for i in range(4):
            forward(100)
            right(90)

    forward(200)

The code above is equivalent to:

    begin_fill()
    for i in range(4):
        forward(100)
        right(90)
    end_fill()

    forward(200)

### 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()`
    `fill()`
    `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 のメソッド
  `poly()`
  `begin_poly()`
  `end_poly()`
  `get_poly()`
  `clone()`
  `getturtle()` | `getpen()`
  `getscreen()`
  `setundobuffer()`
  `undobufferentries()`

### TurtleScreen/Screen のメソッド

ウィンドウの制御
  `bgcolor()`
  `bgpic()`
  `clearscreen()`
  `resetscreen()`
  `screensize()`
  `setworldcoordinates()`
アニメーションの制御
  `no_animation()`
  `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()`
  `save()`
  `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.fill()

  Fill the shape drawn in the `with turtle.fill():` block.

      >>> turtle.color("black", "red")
      >>> with turtle.fill():
      ...     turtle.circle(80)

  Using `fill()` is equivalent to adding the `begin_fill()` before the fill-block and `end_fill()` after the fill-block:

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

  Added in version 3.14.

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

  Record the vertices of a polygon drawn in the `with turtle.poly():` block. The first and last vertices will be connected.

      >>> with turtle.poly():
      ...     turtle.forward(100)
      ...     turtle.right(60)
      ...     turtle.forward(100)

  Added in version 3.14.

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 -- a string, name of an image file (PNG, GIF, PGM, and PPM) or `"nopic"`, or `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.no_animation()

  Temporarily disable turtle animation. The code written inside the `no_animation` block will not be animated; once the code block is exited, the drawing will appear.

      >>> with screen.no_animation():
      ...     for dist in range(2, 400, 2):
      ...         fd(dist)
      ...         rt(90)

  Added in version 3.14.

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)

  There are four different ways to call this function:

  1. name is the name of an image file (PNG, GIF, PGM, and PPM) and shape is `None`: Install the corresponding image shape.

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

     注釈

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

  2. name is an arbitrary string and shape is the name of an image file (PNG, GIF, PGM, and PPM): Install the corresponding image shape.

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

     注釈

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

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

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

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

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

  バージョン 3.14 で変更: Added support for PNG, PGM, and PPM image formats. Both a shape name and an image file name can be specified.

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.save(filename, overwrite=False)

  Save the current turtle drawing (and turtles) as a PostScript file.

  パラメータ:

    - filename -- the path of the saved PostScript file

    - overwrite -- if `False` and there already exists a file with the given filename, then the function will raise a `FileExistsError`. If it is `True`, the file will be overwritten.

      >>> screen.save("my_drawing.ps")
      >>> screen.save("my_drawing.ps", overwrite=True)

  Added in version 3.14.

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.