Doc/library/turtle.rst

   1
   2 :mod:`turtle` --- Turtle graphics for Tk
   3 ========================================
   4
   5 .. module:: turtle
   6    :platform: Tk
   7    :synopsis: An environment for turtle graphics.
   8 .. moduleauthor:: Guido van Rossum <guido@python.org>
   9
  10
  11 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  12
  13
  14 The :mod:`turtle` module provides turtle graphics primitives, in both an
  15 object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for
  16 the underlying graphics, it needs a version of python installed with Tk support.
  17
  18 The procedural interface uses a pen and a canvas which are automagically created
  19 when any of the functions are called.
  20
  21 The :mod:`turtle` module defines the following functions:
  22
  23
  24 .. function:: degrees()
  25
  26    Set angle measurement units to degrees.
  27
  28
  29 .. function:: radians()
  30
  31    Set angle measurement units to radians.
  32
  33
  34 .. function:: setup(**kwargs)
  35
  36    Sets the size and position of the main window.  Keywords are:
  37
  38    * ``width``: either a size in pixels or a fraction of the screen. The default is
  39      50% of the screen.
  40
  41    * ``height``: either a size in pixels or a fraction of the screen. The default
  42      is 50% of the screen.
  43
  44    * ``startx``: starting position in pixels from the left edge of the screen.
  45      ``None`` is the default value and  centers the window horizontally on screen.
  46
  47    * ``starty``: starting position in pixels from the top edge of the screen.
  48      ``None`` is the default value and  centers the window vertically on screen.
  49
  50    Examples::
  51
  52       # Uses default geometry: 50% x 50% of screen, centered.
  53       setup()
  54
  55       # Sets window to 200x200 pixels, in upper left of screen
  56       setup (width=200, height=200, startx=0, starty=0)
  57
  58       # Sets window to 75% of screen by 50% of screen, and centers it.
  59       setup(width=.75, height=0.5, startx=None, starty=None)
  60
  61
  62 .. function:: title(title_str)
  63
  64    Set the window's title to *title*.
  65
  66
  67 .. function:: done()
  68
  69    Enters the Tk main loop.  The window will continue to  be displayed until the
  70    user closes it or the process is killed.
  71
  72
  73 .. function:: reset()
  74
  75    Clear the screen, re-center the pen, and set variables to the default values.
  76
  77
  78 .. function:: clear()
  79
  80    Clear the screen.
  81
  82
  83 .. function:: tracer(flag)
  84
  85    Set tracing on/off (according to whether flag is true or not). Tracing means
  86    line are drawn more slowly, with an animation of an arrow along the  line.
  87
  88
  89 .. function:: speed(speed)
  90
  91    Set the speed of the turtle. Valid values for the parameter *speed* are
  92    ``'fastest'`` (no delay), ``'fast'``, (delay 5ms), ``'normal'`` (delay 10ms),
  93    ``'slow'`` (delay 15ms), and ``'slowest'`` (delay 20ms).
  94
  95    .. versionadded:: 2.5
  96
  97
  98 .. function:: delay(delay)
  99
 100    Set the speed of the turtle to *delay*, which is given in ms.
 101
 102    .. versionadded:: 2.5
 103
 104
 105 .. function:: forward(distance)
 106
 107    Go forward *distance* steps.
 108
 109
 110 .. function:: backward(distance)
 111
 112    Go backward *distance* steps.
 113
 114
 115 .. function:: left(angle)
 116
 117    Turn left *angle* units. Units are by default degrees, but can be set via the
 118    :func:`degrees` and :func:`radians` functions.
 119
 120
 121 .. function:: right(angle)
 122
 123    Turn right *angle* units. Units are by default degrees, but can be set via the
 124    :func:`degrees` and :func:`radians` functions.
 125
 126
 127 .. function:: up()
 128
 129    Move the pen up --- stop drawing.
 130
 131
 132 .. function:: down()
 133
 134    Move the pen down --- draw when moving.
 135
 136
 137 .. function:: width(width)
 138
 139    Set the line width to *width*.
 140
 141
 142 .. function:: color(s)
 143               color((r, g, b))
 144               color(r, g, b)
 145
 146    Set the pen color.  In the first form, the color is specified as a Tk color
 147    specification as a string.  The second form specifies the color as a tuple of
 148    the RGB values, each in the range [0..1].  For the third form, the color is
 149    specified giving the RGB values as three separate parameters (each in the range
 150    [0..1]).
 151
 152
 153 .. function:: write(text[, move])
 154
 155    Write *text* at the current pen position. If *move* is true, the pen is moved to
 156    the bottom-right corner of the text. By default, *move* is false.
 157
 158
 159 .. function:: fill(flag)
 160
 161    The complete specifications are rather complex, but the recommended  usage is:
 162    call ``fill(1)`` before drawing a path you want to fill, and call ``fill(0)``
 163    when you finish to draw the path.
 164
 165
 166 .. function:: begin_fill()
 167
 168    Switch turtle into filling mode;  Must eventually be followed by a corresponding
 169    end_fill() call. Otherwise it will be ignored.
 170
 171    .. versionadded:: 2.5
 172
 173
 174 .. function:: end_fill()
 175
 176    End filling mode, and fill the shape; equivalent to ``fill(0)``.
 177
 178    .. versionadded:: 2.5
 179
 180
 181 .. function:: circle(radius[, extent])
 182
 183    Draw a circle with radius *radius* whose center-point is *radius* units left of
 184    the turtle. *extent* determines which part of a circle is drawn: if not given it
 185    defaults to a full circle.
 186
 187    If *extent* is not a full circle, one endpoint of the arc is the current pen
 188    position. The arc is drawn in a counter clockwise direction if *radius* is
 189    positive, otherwise in a clockwise direction.  In the process, the direction of
 190    the turtle is changed by the amount of the *extent*.
 191
 192
 193 .. function:: goto(x, y)
 194               goto((x, y))
 195
 196    Go to co-ordinates *x*, *y*.  The co-ordinates may be specified either as two
 197    separate arguments or as a 2-tuple.
 198
 199
 200 .. function:: towards(x, y)
 201
 202    Return the angle of the line from the turtle's position to the point *x*, *y*.
 203    The co-ordinates may be specified either as two separate arguments, as a
 204    2-tuple, or as another pen object.
 205
 206    .. versionadded:: 2.5
 207
 208
 209 .. function:: heading()
 210
 211    Return the current orientation of the turtle.
 212
 213    .. versionadded:: 2.3
 214
 215
 216 .. function:: setheading(angle)
 217
 218    Set the orientation of the turtle to *angle*.
 219
 220    .. versionadded:: 2.3
 221
 222
 223 .. function:: position()
 224
 225    Return the current location of the turtle as an ``(x,y)`` pair.
 226
 227    .. versionadded:: 2.3
 228
 229
 230 .. function:: setx(x)
 231
 232    Set the x coordinate of the turtle to *x*.
 233
 234    .. versionadded:: 2.3
 235
 236
 237 .. function:: sety(y)
 238
 239    Set the y coordinate of the turtle to *y*.
 240
 241    .. versionadded:: 2.3
 242
 243
 244 .. function:: window_width()
 245
 246    Return the width of the canvas window.
 247
 248    .. versionadded:: 2.3
 249
 250
 251 .. function:: window_height()
 252
 253    Return the height of the canvas window.
 254
 255    .. versionadded:: 2.3
 256
 257 This module also does ``from math import *``, so see the documentation for the
 258 :mod:`math` module for additional constants and functions useful for turtle
 259 graphics.
 260
 261
 262 .. function:: demo()
 263
 264    Exercise the module a bit.
 265
 266
 267 .. exception:: Error
 268
 269    Exception raised on any error caught by this module.
 270
 271 For examples, see the code of the :func:`demo` function.
 272
 273 This module defines the following classes:
 274
 275
 276 .. class:: Pen()
 277
 278    Define a pen. All above functions can be called as a methods on the given pen.
 279    The constructor automatically creates a canvas do be drawn on.
 280
 281
 282 .. class:: Turtle()
 283
 284    Define a pen. This is essentially a synonym for ``Pen()``; :class:`Turtle` is an
 285    empty subclass of :class:`Pen`.
 286
 287
 288 .. class:: RawPen(canvas)
 289
 290    Define a pen which draws on a canvas *canvas*. This is useful if  you want to
 291    use the module to create graphics in a "real" program.
 292
 293
 294 .. _pen-rawpen-objects:
 295
 296 Turtle, Pen and RawPen Objects
 297 ------------------------------
 298
 299 Most of the global functions available in the module are also available as
 300 methods of the :class:`Turtle`, :class:`Pen` and :class:`RawPen` classes,
 301 affecting only the state of the given pen.
 302
 303 The only method which is more powerful as a method is :func:`degrees`, which
 304 takes an optional argument letting  you specify the number of units
 305 corresponding to a full circle:
 306
 307
 308 .. method:: Turtle.degrees([fullcircle])
 309
 310    *fullcircle* is by default 360. This can cause the pen to have any angular units
 311    whatever: give *fullcircle* ``2*pi`` for radians, or 400 for gradians.
 312