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

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

======================================================================


はじめに
========

タートルグラフィックスは子供向けのプログラミングに入門でよく用いられま
す。 タートルグラフィックスは Wally Feurzeig, Seymour Papert, Cynthia
Solomon が 1967に開発したオリジナルの Logo プログラミング言語の一部分
です。

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.

[画像]

   from turtle import *
   color('red', 'yellow')
   begin_fill()
   while True:
       forward(200)
       left(170)
       if abs(pos()) < 1:
           break
   end_fill()
   done()

これらの命令と他の同様な命令を組み合わせることで、複雑な形や絵が簡単に
描けます。

"turtle" モジュールは同じ名前を持った Python 2.5 までのモジュールの拡
張された再実装です。

再実装に際しては古い turtle モジュールのメリットをそのままに、 (ほぼ)
100% 互換性を保つようにしました。すなわち、まず第一に、学習中のプログ
ラマがモジュールを "-n" スイッチを付けて走らせている IDLE の中から全て
のコマンド、クラス、メソッドを対話的に使えるようにしました。

turtle モジュールはオブジェクト指向と手続き指向の両方の方法でタートル
グラフィックス・プリミティブを提供します。グラフィックスの基礎として
"tkinter" を使っているために、Tk をサポートした Python のバージョンが
必要です。

オブジェクト指向インターフェイスでは、本質的に 2+2 のクラスを使います:

1. "TurtleScreen" クラスはタートルが絵を描きながら走り回る画面を定義し
   ます。そのコンストラクタには "tkinter.Canvas" または
   "ScrolledCanvas" を渡す必要があります。 "turtle" をアプリケーション
   の一部として用いたい場合にはこれを使うべきです。

   "Screen()" 関数は "TurtleScreen" のサブクラスのシングルトンオブジェ
   クトを返します。 "turtle" をグラフィクスを使う一つの独立したツール
   として使う場合には、この関数を呼び出すべきです。シングルトンなので
   、そのクラスからの継承はできません。

   TurtleScreen/Screen の全てのメソッドは関数としても、すなわち、手続
   き指向インターフェイスの一部としても存在しています。

2. "RawTurtle" (別名: "RawPen") は "TurtleScreen" 上に絵を描く Turtle
   オブジェクトを定義します。コンストラクタには Canvas,
   ScrolledCanvas, TurtleScreen のいずれかを引数として渡して RawTurtle
   オブジェクトがどこに絵を描くかを教えます。

   RawTurtle の派生はサブクラス "Turtle" (別名: "Pen") で、 (既に与え
   られているのでなければ自動的に作られた) "唯一の" "Screen" インスタ
   ンスに絵を描きます。

   RawTurtle/Turtle の全てのメソッドは関数としても、すなわち、手続き指
   向インターフェイスの一部としても存在しています。

手続き型インターフェイスでは "Screen" および "Turtle" クラスのメソッド
を元にした関数を提供しています。その名前は対応するメソッドと一緒です。
Screen のメソッドを元にした関数が呼び出されるといつでも screen オブジ
ェクトが自動的に作られます。 Turtle のメソッドを元にした関数が呼び出さ
れるといつでも(名無しの) turtle オブジェクトが自動的に作られます。

複数のタートルを一つのスクリーン上で使いたい場合、オブジェクト指向イン
ターフェイスを使わなければなりません。

注釈:

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


Turtle および Screen のメソッドの概観
=====================================


Turtle のメソッド
-----------------

Turtle の動き
   移動および描画
         "forward()" | "fd()"
         "backward()" | "bk()" | "back()"
         "right()" | "rt()"
         "left()" | "lt()"
         "goto()" | "setpos()" | "setposition()"
         "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()"
         "settiltangle()"
         "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.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")
      >>> turtle.stamp()
      11
      >>> 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):
      ...     turtle.stamp(); turtle.fd(30)
      13
      14
      15
      16
      17
      18
      19
      20
      >>> 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** -- 正の数

   Return or set the pen's attributes x/y-stretchfactors and/or
   outline.  Set resizemode to "user".  If and only if resizemode is
   set to "user", the turtle will be displayed stretched according to
   its stretchfactors: *stretch_wid* is stretchfactor perpendicular to
   its orientation, *stretch_len* is stretchfactor in direction of its
   orientation, *outline* determines the width of the shape's 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.settiltangle(angle)

   パラメータ:
      **angle** -- 数

   タートルの形(turtleshape)を現在の傾斜角に関わらず、指定された角度
   (*angle*)の向きに回転します。タートルの進む方向は *変わりません* 。

      >>> turtle.reset()
      >>> turtle.shape("circle")
      >>> turtle.shapesize(5,2)
      >>> turtle.settiltangle(45)
      >>> turtle.fd(50)
      >>> turtle.settiltangle(-45)
      >>> turtle.fd(50)

   バージョン 3.1 で非推奨.

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. Add as many components to this object as desired, using the
   "addcomponent()" method.

   例えば:

      >>> 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** -- "tkinter.Canvas", "ScrolledCanvas", "TurtleScreen"
      のいずれか

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

class turtle.Turtle

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

class turtle.TurtleScreen(cv)

   パラメータ:
      **cv** -- "tkinter.Canvas"

   Provides screen oriented methods like "bgcolor()" etc. that are
   described above.

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)" 回転


ヘルプと設定
============


ヘルプの使い方
--------------

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" を用意してインポート時に読み込ませその設定に従わせること
ができます。

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

   width = 0.5
   height = 0.75
   leftright = None
   topbottom = None
   canvwidth = 400
   canvheight = 300
   mode = standard
   colormode = 1.0
   delay = 10
   undobuffersize = 1000
   shape = classic
   pencolor = black
   fillcolor = black
   resizemode = noresize
   visible = True
   language = english
   exampleturtle = turtle
   examplescreen = screen
   title = Python Turtle Graphics
   using_IDLE = False

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

* The first four lines correspond to the arguments of the
  "Screen.setup" method.

* Line 5 and 6 correspond to the arguments of the method
  "Screen.screensize".

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

* If you want to use no fill color (i.e. make the turtle transparent),
  you have to write "fillcolor = """ (but all nonempty strings must
  not have quotes in the cfg file).

* タートルにその状態を反映させるためには "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    | turtles as nimsticks,   |
|                  | with three heaps of sticks     | event driven (mouse,    |
|                  | against the computer.          | keyboard)               |
+------------------+--------------------------------+-------------------------+
| paint            | 超極小主義的描画プログラム     | "onclick()"             |
+------------------+--------------------------------+-------------------------+
| peace            | 初歩的                         | turtle: 見た目とアニメ  |
|                  |                                | ーション                |
+------------------+--------------------------------+-------------------------+
| penrose          | 凧と矢による非周期的タイリング | "stamp()"               |
+------------------+--------------------------------+-------------------------+
| planet_and_moon  | 重力系のシミュレーション       | 合成形, "Vec2D"         |
+------------------+--------------------------------+-------------------------+
| rosette          | タートルグラフィックスについて | "clone()", "undo()"     |
|                  | の wikipedia の記事の例        |                         |
+------------------+--------------------------------+-------------------------+
| round_dance      | dancing turtles rotating       | compound shapes, clone  |
|                  | pairwise in opposite direction | shapesize, tilt,        |
|                  |                                | get_shapepoly, update   |
+------------------+--------------------------------+-------------------------+
| sorting_animate  | visual demonstration of        | simple alignment,       |
|                  | different sorting methods      | 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. "settiltangle()" has been deprecated.

* 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.
