1 ========================================

     2 :mod:`turtle` --- Turtle graphics for Tk

     3 ========================================

     4 

     5 .. module:: turtle

     6    :synopsis: Turtle graphics for Tk

     7 .. sectionauthor:: Gregor Lingl <gregor.lingl@aon.at>

     8 

     9 Introduction

    10 ============

    11 

    12 Turtle graphics is a popular way for introducing programming to kids.  It was

    13 part of the original Logo programming language developed by Wally Feurzig and

    14 Seymour Papert in 1966.

    15 

    16 Imagine a robotic turtle starting at (0, 0) in the x-y plane.  Give it the

    17 command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the

    18 direction it is facing, drawing a line as it moves.  Give it the command

    19 ``turtle.left(25)``, and it rotates in-place 25 degrees clockwise.

    20 

    21 By combining together these and similar commands, intricate shapes and pictures

    22 can easily be drawn.

    23 

    24 The :mod:`turtle` module is an extended reimplementation of the same-named

    25 module from the Python standard distribution up to version Python 2.5.

    26 

    27 It tries to keep the merits of the old turtle module and to be (nearly) 100%

    28 compatible with it.  This means in the first place to enable the learning

    29 programmer to use all the commands, classes and methods interactively when using

    30 the module from within IDLE run with the ``-n`` switch.

    31 

    32 The turtle module provides turtle graphics primitives, in both object-oriented

    33 and procedure-oriented ways.  Because it uses :mod:`Tkinter` for the underlying

    34 graphics, it needs a version of python installed with Tk support.

    35 

    36 The object-oriented interface uses essentially two+two classes:

    37 

    38 1. The :class:`TurtleScreen` class defines graphics windows as a playground for

    39    the drawing turtles.  Its constructor needs a :class:`Tkinter.Canvas` or a

    40    :class:`ScrolledCanvas` as argument.  It should be used when :mod:`turtle` is

    41    used as part of some application.

    42 

    43    The function :func:`Screen` returns a singleton object of a

    44    :class:`TurtleScreen` subclass. This function should be used when

    45    :mod:`turtle` is used as a standalone tool for doing graphics.

    46    As a singleton object, inheriting from its class is not possible.

    47 

    48    All methods of TurtleScreen/Screen also exist as functions, i.e. as part of

    49    the procedure-oriented interface.

    50 

    51 2. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw

    52    on a :class:`TurtleScreen`.  Its constructor needs a Canvas, ScrolledCanvas

    53    or TurtleScreen as argument, so the RawTurtle objects know where to draw.

    54 

    55    Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`),

    56    which draws on "the" :class:`Screen` - instance which is automatically

    57    created, if not already present.

    58 

    59    All methods of RawTurtle/Turtle also exist as functions, i.e. part of the

    60    procedure-oriented interface.

    61 

    62 The procedural interface provides functions which are derived from the methods

    63 of the classes :class:`Screen` and :class:`Turtle`.  They have the same names as

    64 the corresponding methods.  A screen object is automativally created whenever a

    65 function derived from a Screen method is called.  An (unnamed) turtle object is

    66 automatically created whenever any of the functions derived from a Turtle method

    67 is called.

    68 

    69 To use multiple turtles an a screen one has to use the object-oriented interface.

    70 

    71 .. note::

    72    In the following documentation the argument list for functions is given.

    73    Methods, of course, have the additional first argument *self* which is

    74    omitted here.

    75 

    76 

    77 Overview over available Turtle and Screen methods

    78 =================================================

    79 

    80 Turtle methods

    81 --------------

    82 

    83 Turtle motion

    84    Move and draw

    85       | :func:`forward` | :func:`fd`

    86       | :func:`backward` | :func:`bk` | :func:`back`

    87       | :func:`right` | :func:`rt`

    88       | :func:`left` | :func:`lt`

    89       | :func:`goto` | :func:`setpos` | :func:`setposition`

    90       | :func:`setx`

    91       | :func:`sety`

    92       | :func:`setheading` | :func:`seth`

    93       | :func:`home`

    94       | :func:`circle`

    95       | :func:`dot`

    96       | :func:`stamp`

    97       | :func:`clearstamp`

    98       | :func:`clearstamps`

    99       | :func:`undo`

   100       | :func:`speed`

   101 

   102    Tell Turtle's state

   103       | :func:`position` | :func:`pos`

   104       | :func:`towards`

   105       | :func:`xcor`

   106       | :func:`ycor`

   107       | :func:`heading`

   108       | :func:`distance`

   109 

   110    Setting and measurement

   111       | :func:`degrees`

   112       | :func:`radians`

   113 

   114 Pen control

   115    Drawing state

   116       | :func:`pendown` | :func:`pd` | :func:`down`

   117       | :func:`penup` | :func:`pu` | :func:`up`

   118       | :func:`pensize` | :func:`width`

   119       | :func:`pen`

   120       | :func:`isdown`

   121 

   122    Color control

   123       | :func:`color`

   124       | :func:`pencolor`

   125       | :func:`fillcolor`

   126 

   127    Filling

   128       | :func:`fill`

   129       | :func:`begin_fill`

   130       | :func:`end_fill`

   131 

   132    More drawing control

   133       | :func:`reset`

   134       | :func:`clear`

   135       | :func:`write`

   136 

   137 Turtle state

   138    Visibility

   139       | :func:`showturtle` | :func:`st`

   140       | :func:`hideturtle` | :func:`ht`

   141       | :func:`isvisible`

   142 

   143    Appearance

   144       | :func:`shape`

   145       | :func:`resizemode`

   146       | :func:`shapesize` | :func:`turtlesize`

   147       | :func:`settiltangle`

   148       | :func:`tiltangle`

   149       | :func:`tilt`

   150 

   151 Using events

   152    | :func:`onclick`

   153    | :func:`onrelease`

   154    | :func:`ondrag`

   155 

   156 Special Turtle methods

   157    | :func:`begin_poly`

   158    | :func:`end_poly`

   159    | :func:`get_poly`

   160    | :func:`clone`

   161    | :func:`getturtle` | :func:`getpen`

   162    | :func:`getscreen`

   163    | :func:`setundobuffer`

   164    | :func:`undobufferentries`

   165    | :func:`tracer`

   166    | :func:`window_width`

   167    | :func:`window_height`

   168 

   169 

   170 Methods of TurtleScreen/Screen

   171 ------------------------------

   172 

   173 Window control

   174    | :func:`bgcolor`

   175    | :func:`bgpic`

   176    | :func:`clear` | :func:`clearscreen`

   177    | :func:`reset` | :func:`resetscreen`

   178    | :func:`screensize`

   179    | :func:`setworldcoordinates`

   180 

   181 Animation control

   182    | :func:`delay`

   183    | :func:`tracer`

   184    | :func:`update`

   185 

   186 Using screen events

   187    | :func:`listen`

   188    | :func:`onkey`

   189    | :func:`onclick` | :func:`onscreenclick`

   190    | :func:`ontimer`

   191 

   192 Settings and special methods

   193    | :func:`mode`

   194    | :func:`colormode`

   195    | :func:`getcanvas`

   196    | :func:`getshapes`

   197    | :func:`register_shape` | :func:`addshape`

   198    | :func:`turtles`

   199    | :func:`window_height`

   200    | :func:`window_width`

   201 

   202 Methods specific to Screen

   203    | :func:`bye`

   204    | :func:`exitonclick`

   205    | :func:`setup`

   206    | :func:`title`

   207 

   208 

   209 Methods of RawTurtle/Turtle and corresponding functions

   210 =======================================================

   211 

   212 Most of the examples in this section refer to a Turtle instance called

   213 ``turtle``.

   214 

   215 Turtle motion

   216 -------------

   217 

   218 .. function:: forward(distance)

   219               fd(distance)

   220 

   221    :param distance: a number (integer or float)

   222 

   223    Move the turtle forward by the specified *distance*, in the direction the

   224    turtle is headed.

   225 

   226    >>> turtle.position()

   227    (0.00, 0.00)

   228    >>> turtle.forward(25)

   229    >>> turtle.position()

   230    (25.00,0.00)

   231    >>> turtle.forward(-75)

   232    >>> turtle.position()

   233    (-50.00,0.00)

   234 

   235 

   236 .. function:: back(distance)

   237               bk(distance)

   238               backward(distance)

   239 

   240    :param distance: a number

   241 

   242    Move the turtle backward by *distance*, opposite to the direction the

   243    turtle is headed.  Do not change the turtle's heading.

   244 

   245    >>> turtle.position()

   246    (0.00, 0.00)

   247    >>> turtle.backward(30)

   248    >>> turtle.position()

   249    (-30.00, 0.00)

   250 

   251 

   252 .. function:: right(angle)

   253               rt(angle)

   254 

   255    :param angle: a number (integer or float)

   256 

   257    Turn turtle right by *angle* units.  (Units are by default degrees, but

   258    can be set via the :func:`degrees` and :func:`radians` functions.)  Angle

   259    orientation depends on the turtle mode, see :func:`mode`.

   260 

   261    >>> turtle.heading()

   262    22.0

   263    >>> turtle.right(45)

   264    >>> turtle.heading()

   265    337.0

   266 

   267 

   268 .. function:: left(angle)

   269               lt(angle)

   270 

   271    :param angle: a number (integer or float)

   272 

   273    Turn turtle left by *angle* units.  (Units are by default degrees, but

   274    can be set via the :func:`degrees` and :func:`radians` functions.)  Angle

   275    orientation depends on the turtle mode, see :func:`mode`.

   276 

   277    >>> turtle.heading()

   278    22.0

   279    >>> turtle.left(45)

   280    >>> turtle.heading()

   281    67.0

   282 

   283 .. function:: goto(x, y=None)

   284               setpos(x, y=None)

   285               setposition(x, y=None)

   286 

   287     :param x: a number or a pair/vector of numbers

   288     :param y: a number or ``None``

   289 

   290     If *y* is ``None``, *x* must be a pair of coordinates or a :class:`Vec2D`

   291     (e.g. as returned by :func:`pos`).

   292 

   293     Move turtle to an absolute position.  If the pen is down, draw line.  Do

   294     not change the turtle's orientation.

   295 

   296     >>> tp = turtle.pos()

   297     >>> tp

   298     (0.00, 0.00)

   299     >>> turtle.setpos(60,30)

   300     >>> turtle.pos()

   301     (60.00,30.00)

   302     >>> turtle.setpos((20,80))

   303     >>> turtle.pos()

   304     (20.00,80.00)

   305     >>> turtle.setpos(tp)

   306     >>> turtle.pos()

   307     (0.00,0.00)

   308 

   309 

   310 .. function:: setx(x)

   311 

   312    :param x: a number (integer or float)

   313 

   314    Set the turtle's first coordinate to *x*, leave second coordinate

   315    unchanged.

   316 

   317    >>> turtle.position()

   318    (0.00, 240.00)

   319    >>> turtle.setx(10)

   320    >>> turtle.position()

   321    (10.00, 240.00)

   322 

   323 

   324 .. function:: sety(y)

   325 

   326    :param y: a number (integer or float)

   327 

   328    Set the turtle's first coordinate to *y*, leave second coordinate

   329    unchanged.

   330 

   331    >>> turtle.position()

   332    (0.00, 40.00)

   333    >>> turtle.sety(-10)

   334    >>> turtle.position()

   335    (0.00, -10.00)

   336 

   337 

   338 .. function:: setheading(to_angle)

   339               seth(to_angle)

   340 

   341    :param to_angle: a number (integer or float)

   342 

   343    Set the orientation of the turtle to *to_angle*.  Here are some common

   344    directions in degrees:

   345 

   346    =================== ====================

   347     standard mode           logo mode

   348    =================== ====================

   349       0 - east                0 - north

   350      90 - north              90 - east

   351     180 - west              180 - south

   352     270 - south             270 - west

   353    =================== ====================

   354 

   355    >>> turtle.setheading(90)

   356    >>> turtle.heading()

   357    90

   358 

   359 

   360 .. function:: home()

   361 

   362    Move turtle to the origin -- coordinates (0,0) -- and set its heading to

   363    its start-orientation (which depends on the mode, see :func:`mode`).

   364 

   365 

   366 .. function:: circle(radius, extent=None, steps=None)

   367 

   368    :param radius: a number

   369    :param extent: a number (or ``None``)

   370    :param steps: an integer (or ``None``)

   371 

   372    Draw a circle with given *radius*.  The center is *radius* units left of

   373    the turtle; *extent* -- an angle -- determines which part of the circle

   374    is drawn.  If *extent* is not given, draw the entire circle.  If *extent*

   375    is not a full circle, one endpoint of the arc is the current pen

   376    position.  Draw the arc in counterclockwise direction if *radius* is

   377    positive, otherwise in clockwise direction.  Finally the direction of the

   378    turtle is changed by the amount of *extent*.

   379 

   380    As the circle is approximated by an inscribed regular polygon, *steps*

   381    determines the number of steps to use.  If not given, it will be

   382    calculated automatically.  May be used to draw regular polygons.

   383 

   384    >>> turtle.circle(50)

   385    >>> turtle.circle(120, 180)  # draw a semicircle

   386 

   387 

   388 .. function:: dot(size=None, *color)

   389 

   390    :param size: an integer >= 1 (if given)

   391    :param color: a colorstring or a numeric color tuple

   392 

   393    Draw a circular dot with diameter *size*, using *color*.  If *size* is

   394    not given, the maximum of pensize+4 and 2*pensize is used.

   395 

   396    >>> turtle.dot()

   397    >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)

   398 

   399 

   400 .. function:: stamp()

   401 

   402    Stamp a copy of the turtle shape onto the canvas at the current turtle

   403    position.  Return a stamp_id for that stamp, which can be used to delete

   404    it by calling ``clearstamp(stamp_id)``.

   405 

   406    >>> turtle.color("blue")

   407    >>> turtle.stamp()

   408    13

   409    >>> turtle.fd(50)

   410 

   411 

   412 .. function:: clearstamp(stampid)

   413 

   414    :param stampid: an integer, must be return value of previous

   415                    :func:`stamp` call

   416 

   417    Delete stamp with given *stampid*.

   418 

   419    >>> turtle.color("blue")

   420    >>> astamp = turtle.stamp()

   421    >>> turtle.fd(50)

   422    >>> turtle.clearstamp(astamp)

   423 

   424 

   425 .. function:: clearstamps(n=None)

   426 

   427    :param n: an integer (or ``None``)

   428 

   429    Delete all or first/last *n* of turtle's stamps.  If *n* is None, delete

   430    all stamps, if *n* > 0 delete first *n* stamps, else if *n* < 0 delete

   431    last *n* stamps.

   432 

   433    >>> for i in range(8):

   434    ...     turtle.stamp(); turtle.fd(30)

   435    >>> turtle.clearstamps(2)

   436    >>> turtle.clearstamps(-2)

   437    >>> turtle.clearstamps()

   438 

   439 

   440 .. function:: undo()

   441 

   442    Undo (repeatedly) the last turtle action(s).  Number of available

   443    undo actions is determined by the size of the undobuffer.

   444 

   445    >>> for i in range(4):

   446    ...     turtle.fd(50); turtle.lt(80)

   447    ...

   448    >>> for i in range(8):

   449    ...     turtle.undo()

   450 

   451 

   452 .. function:: speed(speed=None)

   453 

   454    :param speed: an integer in the range 0..10 or a speedstring (see below)

   455 

   456    Set the turtle's speed to an integer value in the range 0..10.  If no

   457    argument is given, return current speed.

   458 

   459    If input is a number greater than 10 or smaller than 0.5, speed is set

   460    to 0.  Speedstrings are mapped to speedvalues as follows:

   461 

   462    * "fastest":  0

   463    * "fast":  10

   464    * "normal":  6

   465    * "slow":  3

   466    * "slowest":  1

   467 

   468    Speeds from 1 to 10 enforce increasingly faster animation of line drawing

   469    and turtle turning.

   470 

   471    Attention: *speed* = 0 means that *no* animation takes

   472    place. forward/back makes turtle jump and likewise left/right make the

   473    turtle turn instantly.

   474 

   475    >>> turtle.speed(3)

   476 

   477 

   478 Tell Turtle's state

   479 -------------------

   480 

   481 .. function:: position()

   482               pos()

   483 

   484    Return the turtle's current location (x,y) (as a :class:`Vec2D` vector).

   485 

   486    >>> turtle.pos()

   487    (0.00, 240.00)

   488 

   489 

   490 .. function:: towards(x, y=None)

   491 

   492    :param x: a number or a pair/vector of numbers or a turtle instance

   493    :param y: a number if *x* is a number, else ``None``

   494 

   495    Return the angle between the line from turtle position to position specified

   496    by (x,y), the vector or the other turtle.  This depends on the turtle's start

   497    orientation which depends on the mode - "standard"/"world" or "logo").

   498 

   499    >>> turtle.pos()

   500    (10.00, 10.00)

   501    >>> turtle.towards(0,0)

   502    225.0

   503 

   504 

   505 .. function:: xcor()

   506 

   507    Return the turtle's x coordinate.

   508 

   509    >>> reset()

   510    >>> turtle.left(60)

   511    >>> turtle.forward(100)

   512    >>> print turtle.xcor()

   513    50.0

   514 

   515 

   516 .. function:: ycor()

   517 

   518    Return the turtle's y coordinate.

   519 

   520    >>> reset()

   521    >>> turtle.left(60)

   522    >>> turtle.forward(100)

   523    >>> print turtle.ycor()

   524    86.6025403784

   525 

   526 

   527 .. function:: heading()

   528 

   529    Return the turtle's current heading (value depends on the turtle mode, see

   530    :func:`mode`).

   531 

   532    >>> turtle.left(67)

   533    >>> turtle.heading()

   534    67.0

   535 

   536 

   537 .. function:: distance(x, y=None)

   538 

   539    :param x: a number or a pair/vector of numbers or a turtle instance

   540    :param y: a number if *x* is a number, else ``None``

   541 

   542    Return the distance from the turtle to (x,y), the given vector, or the given

   543    other turtle, in turtle step units.

   544 

   545    >>> turtle.pos()

   546    (0.00, 0.00)

   547    >>> turtle.distance(30,40)

   548    50.0

   549    >>> joe = Turtle()

   550    >>> joe.forward(77)

   551    >>> turtle.distance(joe)

   552    77.0

   553 

   554 

   555 Settings for measurement

   556 ------------------------

   557 

   558 .. function:: degrees(fullcircle=360.0)

   559 

   560    :param fullcircle: a number

   561 

   562    Set angle measurement units, i.e. set number of "degrees" for a full circle.

   563    Default value is 360 degrees.

   564 

   565    >>> turtle.left(90)

   566    >>> turtle.heading()

   567    90

   568    >>> turtle.degrees(400.0)  # angle measurement in gon

   569    >>> turtle.heading()

   570    100

   571 

   572 

   573 .. function:: radians()

   574 

   575    Set the angle measurement units to radians.  Equivalent to

   576    ``degrees(2*math.pi)``.

   577 

   578    >>> turtle.heading()

   579    90

   580    >>> turtle.radians()

   581    >>> turtle.heading()

   582    1.5707963267948966

   583 

   584 

   585 Pen control

   586 -----------

   587 

   588 Drawing state

   589 ~~~~~~~~~~~~~

   590 

   591 .. function:: pendown()

   592               pd()

   593               down()

   594 

   595    Pull the pen down -- drawing when moving.

   596 

   597 

   598 .. function:: penup()

   599               pu()

   600               up()

   601 

   602    Pull the pen up -- no drawing when moving.

   603 

   604 

   605 .. function:: pensize(width=None)

   606               width(width=None)

   607 

   608    :param width: a positive number

   609 

   610    Set the line thickness to *width* or return it.  If resizemode is set to

   611    "auto" and turtleshape is a polygon, that polygon is drawn with the same line

   612    thickness.  If no argument is given, the current pensize is returned.

   613 

   614    >>> turtle.pensize()

   615    1

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

   617 

   618 

   619 .. function:: pen(pen=None, **pendict)

   620 

   621    :param pen: a dictionary with some or all of the below listed keys

   622    :param pendict: one or more keyword-arguments with the below listed keys as keywords

   623 

   624    Return or set the pen's attributes in a "pen-dictionary" with the following

   625    key/value pairs:

   626 

   627    * "shown": True/False

   628    * "pendown": True/False

   629    * "pencolor": color-string or color-tuple

   630    * "fillcolor": color-string or color-tuple

   631    * "pensize": positive number

   632    * "speed": number in range 0..10

   633    * "resizemode": "auto" or "user" or "noresize"

   634    * "stretchfactor": (positive number, positive number)

   635    * "outline": positive number

   636    * "tilt": number

   637 

   638    This dicionary can be used as argument for a subsequent call to :func:`pen`

   639    to restore the former pen-state.  Moreover one or more of these attributes

   640    can be provided as keyword-arguments.  This can be used to set several pen

   641    attributes in one statement.

   642 

   643    >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)

   644    >>> turtle.pen()

   645    {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,

   646    'pencolor': 'red', 'pendown': True, 'fillcolor': 'black',

   647    'stretchfactor': (1,1), 'speed': 3}

   648    >>> penstate=turtle.pen()

   649    >>> turtle.color("yellow","")

   650    >>> turtle.penup()

   651    >>> turtle.pen()

   652    {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,

   653    'pencolor': 'yellow', 'pendown': False, 'fillcolor': '',

   654    'stretchfactor': (1,1), 'speed': 3}

   655    >>> p.pen(penstate, fillcolor="green")

   656    >>> p.pen()

   657    {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,

   658    'pencolor': 'red', 'pendown': True, 'fillcolor': 'green',

   659    'stretchfactor': (1,1), 'speed': 3}

   660 

   661 

   662 .. function:: isdown()

   663 

   664    Return ``True`` if pen is down, ``False`` if it's up.

   665 

   666    >>> turtle.penup()

   667    >>> turtle.isdown()

   668    False

   669    >>> turtle.pendown()

   670    >>> turtle.isdown()

   671    True

   672 

   673 

   674 Color control

   675 ~~~~~~~~~~~~~

   676 

   677 .. function:: pencolor(*args)

   678 

   679    Return or set the pencolor.

   680 

   681    Four input formats are allowed:

   682 

   683    ``pencolor()``

   684       Return the current pencolor as color specification string, possibly in

   685       hex-number format (see example).  May be used as input to another

   686       color/pencolor/fillcolor call.

   687 

   688    ``pencolor(colorstring)``

   689       Set pencolor to *colorstring*, which is a Tk color specification string,

   690       such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.

   691 

   692    ``pencolor((r, g, b))``

   693       Set pencolor to the RGB color represented by the tuple of *r*, *g*, and

   694       *b*.  Each of *r*, *g*, and *b* must be in the range 0..colormode, where

   695       colormode is either 1.0 or 255 (see :func:`colormode`).

   696 

   697    ``pencolor(r, g, b)``

   698       Set pencolor to the RGB color represented by *r*, *g*, and *b*.  Each of

   699       *r*, *g*, and *b* must be in the range 0..colormode.

   700 

   701     If turtleshape is a polygon, the outline of that polygon is drawn with the

   702     newly set pencolor.

   703 

   704     >>> turtle.pencolor("brown")

   705     >>> tup = (0.2, 0.8, 0.55)

   706     >>> turtle.pencolor(tup)

   707     >>> turtle.pencolor()

   708     "#33cc8c"

   709 

   710 

   711 .. function:: fillcolor(*args)

   712 

   713    Return or set the fillcolor.

   714 

   715    Four input formats are allowed:

   716 

   717    ``fillcolor()``

   718       Return the current fillcolor as color specification string, possibly in

   719       hex-number format (see example).  May be used as input to another

   720       color/pencolor/fillcolor call.

   721 

   722    ``fillcolor(colorstring)``

   723       Set fillcolor to *colorstring*, which is a Tk color specification string,

   724       such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.

   725 

   726    ``fillcolor((r, g, b))``

   727       Set fillcolor to the RGB color represented by the tuple of *r*, *g*, and

   728       *b*.  Each of *r*, *g*, and *b* must be in the range 0..colormode, where

   729       colormode is either 1.0 or 255 (see :func:`colormode`).

   730 

   731    ``fillcolor(r, g, b)``

   732       Set fillcolor to the RGB color represented by *r*, *g*, and *b*.  Each of

   733       *r*, *g*, and *b* must be in the range 0..colormode.

   734 

   735     If turtleshape is a polygon, the interior of that polygon is drawn

   736     with the newly set fillcolor.

   737 

   738     >>> turtle.fillcolor("violet")

   739     >>> col = turtle.pencolor()

   740     >>> turtle.fillcolor(col)

   741     >>> turtle.fillcolor(0, .5, 0)

   742 

   743 

   744 .. function:: color(*args)

   745 

   746    Return or set pencolor and fillcolor.

   747 

   748    Several input formats are allowed.  They use 0 to 3 arguments as

   749    follows:

   750 

   751    ``color()``

   752       Return the current pencolor and the current fillcolor as a pair of color

   753       specification strings as returned by :func:`pencolor` and

   754       :func:`fillcolor`.

   755 

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

   757       Inputs as in :func:`pencolor`, set both, fillcolor and pencolor, to the

   758       given value.

   759 

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

   761       Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)``

   762       and analogously if the other input format is used.

   763 

   764     If turtleshape is a polygon, outline and interior of that polygon is drawn

   765     with the newly set colors.

   766 

   767     >>> turtle.color("red", "green")

   768     >>> turtle.color()

   769     ("red", "green")

   770     >>> colormode(255)

   771     >>> color((40, 80, 120), (160, 200, 240))

   772     >>> color()

   773     ("#285078", "#a0c8f0")

   774 

   775 

   776 See also: Screen method :func:`colormode`.

   777 

   778 

   779 Filling

   780 ~~~~~~~

   781 

   782 .. function:: fill(flag)

   783 

   784    :param flag: True/False (or 1/0 respectively)

   785 

   786    Call ``fill(True)`` before drawing the shape you want to fill, and

   787    ``fill(False)`` when done.  When used without argument: return fillstate

   788    (``True`` if filling, ``False`` else).

   789 

   790    >>> turtle.fill(True)

   791    >>> for _ in range(3):

   792    ...    turtle.forward(100)

   793    ...    turtle.left(120)

   794    ...

   795    >>> turtle.fill(False)

   796 

   797 

   798 .. function:: begin_fill()

   799 

   800    Call just before drawing a shape to be filled.  Equivalent to ``fill(True)``.

   801 

   802    >>> turtle.color("black", "red")

   803    >>> turtle.begin_fill()

   804    >>> turtle.circle(60)

   805    >>> turtle.end_fill()

   806 

   807 

   808 .. function:: end_fill()

   809 

   810    Fill the shape drawn after the last call to :func:`begin_fill`.  Equivalent

   811    to ``fill(False)``.

   812 

   813 

   814 More drawing control

   815 ~~~~~~~~~~~~~~~~~~~~

   816 

   817 .. function:: reset()

   818 

   819    Delete the turtle's drawings from the screen, re-center the turtle and set

   820    variables to the default values.

   821 

   822    >>> turtle.position()

   823    (0.00,-22.00)

   824    >>> turtle.heading()

   825    100.0

   826    >>> turtle.reset()

   827    >>> turtle.position()

   828    (0.00,0.00)

   829    >>> turtle.heading()

   830    0.0

   831 

   832 

   833 .. function:: clear()

   834 

   835    Delete the turtle's drawings from the screen.  Do not move turtle.  State and

   836    position of the turtle as well as drawings of other turtles are not affected.

   837 

   838 

   839 .. function:: write(arg, move=False, align="left", font=("Arial", 8, "normal"))

   840 

   841    :param arg: object to be written to the TurtleScreen

   842    :param move: True/False

   843    :param align: one of the strings "left", "center" or right"

   844    :param font: a triple (fontname, fontsize, fonttype)

   845 

   846    Write text - the string representation of *arg* - at the current turtle

   847    position according to *align* ("left", "center" or right") and with the given

   848    font.  If *move* is True, the pen is moved to the bottom-right corner of the

   849    text.  By default, *move* is False.

   850 

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

   852    >>> turtle.write((0,0), True)

   853 

   854 

   855 Turtle state

   856 ------------

   857 

   858 Visibility

   859 ~~~~~~~~~~

   860 

   861 .. function:: showturtle()

   862               st()

   863 

   864    Make the turtle visible.

   865 

   866    >>> turtle.hideturtle()

   867    >>> turtle.showturtle()

   868 

   869 

   870 .. function:: hideturtle()

   871               ht()

   872 

   873    Make the turtle invisible.  It's a good idea to do this while you're in the

   874    middle of doing some complex drawing, because hiding the turtle speeds up the

   875    drawing observably.

   876 

   877    >>> turtle.hideturtle()

   878 

   879 

   880 .. function:: isvisible()

   881 

   882    Return True if the Turtle is shown, False if it's hidden.

   883 

   884    >>> turtle.hideturtle()

   885    >>> print turtle.isvisible():

   886    False

   887 

   888 

   889 Appearance

   890 ~~~~~~~~~~

   891 

   892 .. function:: shape(name=None)

   893 

   894    :param name: a string which is a valid shapename

   895 

   896    Set turtle shape to shape with given *name* or, if name is not given, return

   897    name of current shape.  Shape with *name* must exist in the TurtleScreen's

   898    shape dictionary.  Initially there are the following polygon shapes: "arrow",

   899    "turtle", "circle", "square", "triangle", "classic".  To learn about how to

   900    deal with shapes see Screen method :func:`register_shape`.

   901 

   902    >>> turtle.shape()

   903    "arrow"

   904    >>> turtle.shape("turtle")

   905    >>> turtle.shape()

   906    "turtle"

   907 

   908 

   909 .. function:: resizemode(rmode=None)

   910 

   911    :param rmode: one of the strings "auto", "user", "noresize"

   912 

   913    Set resizemode to one of the values: "auto", "user", "noresize".  If *rmode*

   914    is not given, return current resizemode.  Different resizemodes have the

   915    following effects:

   916 

   917    - "auto": adapts the appearance of the turtle corresponding to the value of pensize.

   918    - "user": adapts the appearance of the turtle according to the values of

   919      stretchfactor and outlinewidth (outline), which are set by

   920      :func:`shapesize`.

   921    - "noresize": no adaption of the turtle's appearance takes place.

   922 

   923    resizemode("user") is called by :func:`shapesize` when used with arguments.

   924 

   925    >>> turtle.resizemode("noresize")

   926    >>> turtle.resizemode()

   927    "noresize"

   928 

   929 

   930 .. function:: shapesize(stretch_wid=None, stretch_len=None, outline=None)

   931 

   932    :param stretch_wid: positive number

   933    :param stretch_len: positive number

   934    :param outline: positive number

   935 

   936    Return or set the pen's attributes x/y-stretchfactors and/or outline.  Set

   937    resizemode to "user".  If and only if resizemode is set to "user", the turtle

   938    will be displayed stretched according to its stretchfactors: *stretch_wid* is

   939    stretchfactor perpendicular to its orientation, *stretch_len* is

   940    stretchfactor in direction of its orientation, *outline* determines the width

   941    of the shapes's outline.

   942 

   943    >>> turtle.resizemode("user")

   944    >>> turtle.shapesize(5, 5, 12)

   945    >>> turtle.shapesize(outline=8)

   946 

   947 

   948 .. function:: tilt(angle)

   949 

   950    :param angle: a number

   951 

   952    Rotate the turtleshape by *angle* from its current tilt-angle, but do *not*

   953    change the turtle's heading (direction of movement).

   954 

   955    >>> turtle.shape("circle")

   956    >>> turtle.shapesize(5,2)

   957    >>> turtle.tilt(30)

   958    >>> turtle.fd(50)

   959    >>> turtle.tilt(30)

   960    >>> turtle.fd(50)

   961 

   962 

   963 .. function:: settiltangle(angle)

   964 

   965    :param angle: a number

   966 

   967    Rotate the turtleshape to point in the direction specified by *angle*,

   968    regardless of its current tilt-angle.  *Do not* change the turtle's heading

   969    (direction of movement).

   970 

   971    >>> turtle.shape("circle")

   972    >>> turtle.shapesize(5,2)

   973    >>> turtle.settiltangle(45)

   974    >>> stamp()

   975    >>> turtle.fd(50)

   976    >>> turtle.settiltangle(-45)

   977    >>> stamp()

   978    >>> turtle.fd(50)

   979 

   980 

   981 .. function:: tiltangle()

   982 

   983    Return the current tilt-angle, i.e. the angle between the orientation of the

   984    turtleshape and the heading of the turtle (its direction of movement).

   985 

   986    >>> turtle.shape("circle")

   987    >>> turtle.shapesize(5,2)

   988    >>> turtle.tilt(45)

   989    >>> turtle.tiltangle()

   990    45

   991 

   992 

   993 Using events

   994 ------------

   995 

   996 .. function:: onclick(fun, btn=1, add=None)

   997 

   998    :param fun: a function with two arguments which will be called with the

   999                coordinates of the clicked point on the canvas

  1000    :param num: number of the mouse-button, defaults to 1 (left mouse button)

  1001    :param add: ``True`` or ``False`` -- if ``True``, a new binding will be

  1002                added, otherwise it will replace a former binding

  1003 

  1004    Bind *fun* to mouse-click events on this turtle.  If *fun* is ``None``,

  1005    existing bindings are removed.  Example for the anonymous turtle, i.e. the

  1006    procedural way:

  1007 

  1008    >>> def turn(x, y):

  1009    ...     left(180)

  1010    ...

  1011    >>> onclick(turn)  # Now clicking into the turtle will turn it.

  1012    >>> onclick(None)  # event-binding will be removed

  1013 

  1014 

  1015 .. function:: onrelease(fun, btn=1, add=None)

  1016 

  1017    :param fun: a function with two arguments which will be called with the

  1018                coordinates of the clicked point on the canvas

  1019    :param num: number of the mouse-button, defaults to 1 (left mouse button)

  1020    :param add: ``True`` or ``False`` -- if ``True``, a new binding will be

  1021                added, otherwise it will replace a former binding

  1022 

  1023    Bind *fun* to mouse-button-release events on this turtle.  If *fun* is

  1024    ``None``, existing bindings are removed.

  1025 

  1026    >>> class MyTurtle(Turtle):

  1027    ...     def glow(self,x,y):

  1028    ...         self.fillcolor("red")

  1029    ...     def unglow(self,x,y):

  1030    ...         self.fillcolor("")

  1031    ...

  1032    >>> turtle = MyTurtle()

  1033    >>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,

  1034    >>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.

  1035 

  1036 

  1037 .. function:: ondrag(fun, btn=1, add=None)

  1038 

  1039    :param fun: a function with two arguments which will be called with the

  1040                coordinates of the clicked point on the canvas

  1041    :param num: number of the mouse-button, defaults to 1 (left mouse button)

  1042    :param add: ``True`` or ``False`` -- if ``True``, a new binding will be

  1043                added, otherwise it will replace a former binding

  1044 

  1045    Bind *fun* to mouse-move events on this turtle.  If *fun* is ``None``,

  1046    existing bindings are removed.

  1047 

  1048    Remark: Every sequence of mouse-move-events on a turtle is preceded by a

  1049    mouse-click event on that turtle.

  1050 

  1051    >>> turtle.ondrag(turtle.goto)

  1052    # Subsequently, clicking and dragging the Turtle will move it across

  1053    # the screen thereby producing handdrawings (if pen is down).

  1054 

  1055 

  1056 Special Turtle methods

  1057 ----------------------

  1058 

  1059 .. function:: begin_poly()

  1060 

  1061    Start recording the vertices of a polygon.  Current turtle position is first

  1062    vertex of polygon.

  1063 

  1064 

  1065 .. function:: end_poly()

  1066 

  1067    Stop recording the vertices of a polygon.  Current turtle position is last

  1068    vertex of polygon.  This will be connected with the first vertex.

  1069 

  1070 

  1071 .. function:: get_poly()

  1072 

  1073    Return the last recorded polygon.

  1074 

  1075    >>> p = turtle.get_poly()

  1076    >>> turtle.register_shape("myFavouriteShape", p)

  1077 

  1078 

  1079 .. function:: clone()

  1080 

  1081    Create and return a clone of the turtle with same position, heading and

  1082    turtle properties.

  1083 

  1084    >>> mick = Turtle()

  1085    >>> joe = mick.clone()

  1086 

  1087 

  1088 .. function:: getturtle()

  1089 

  1090    Return the Turtle object itself.  Only reasonable use: as a function to

  1091    return the "anonymous turtle":

  1092 

  1093    >>> pet = getturtle()

  1094    >>> pet.fd(50)

  1095    >>> pet

  1096    <turtle.Turtle object at 0x01417350>

  1097    >>> turtles()

  1098    [<turtle.Turtle object at 0x01417350>]

  1099 

  1100 

  1101 .. function:: getscreen()

  1102 

  1103    Return the :class:`TurtleScreen` object the turtle is drawing on.

  1104    TurtleScreen methods can then be called for that object.

  1105 

  1106    >>> ts = turtle.getscreen()

  1107    >>> ts

  1108    <turtle.Screen object at 0x01417710>

  1109    >>> ts.bgcolor("pink")

  1110 

  1111 

  1112 .. function:: setundobuffer(size)

  1113 

  1114    :param size: an integer or ``None``

  1115 

  1116    Set or disable undobuffer.  If *size* is an integer an empty undobuffer of

  1117    given size is installed.  *size* gives the maximum number of turtle actions

  1118    that can be undone by the :func:`undo` method/function.  If *size* is

  1119    ``None``, the undobuffer is disabled.

  1120 

  1121    >>> turtle.setundobuffer(42)

  1122 

  1123 

  1124 .. function:: undobufferentries()

  1125 

  1126    Return number of entries in the undobuffer.

  1127 

  1128    >>> while undobufferentries():

  1129    ...     undo()

  1130 

  1131 

  1132 .. function:: tracer(flag=None, delay=None)

  1133 

  1134    A replica of the corresponding TurtleScreen method.

  1135