PageRenderTime 56ms CodeModel.GetById 14ms app.highlight 31ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/library/turtle.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 2226 lines | 1547 code | 679 blank | 0 comment | 0 complexity | b15a8100e0c3f8effa31d3387efffa71 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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.. testsetup:: default
  10
  11   from turtle import *
  12   turtle = Turtle()
  13
  14Introduction
  15============
  16
  17Turtle graphics is a popular way for introducing programming to kids.  It was
  18part of the original Logo programming language developed by Wally Feurzig and
  19Seymour Papert in 1966.
  20
  21Imagine a robotic turtle starting at (0, 0) in the x-y plane.  Give it the
  22command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the
  23direction it is facing, drawing a line as it moves.  Give it the command
  24``turtle.left(25)``, and it rotates in-place 25 degrees clockwise.
  25
  26By combining together these and similar commands, intricate shapes and pictures
  27can easily be drawn.
  28
  29The :mod:`turtle` module is an extended reimplementation of the same-named
  30module from the Python standard distribution up to version Python 2.5.
  31
  32It tries to keep the merits of the old turtle module and to be (nearly) 100%
  33compatible with it.  This means in the first place to enable the learning
  34programmer to use all the commands, classes and methods interactively when using
  35the module from within IDLE run with the ``-n`` switch.
  36
  37The turtle module provides turtle graphics primitives, in both object-oriented
  38and procedure-oriented ways.  Because it uses :mod:`Tkinter` for the underlying
  39graphics, it needs a version of python installed with Tk support.
  40
  41The object-oriented interface uses essentially two+two classes:
  42
  431. The :class:`TurtleScreen` class defines graphics windows as a playground for
  44   the drawing turtles.  Its constructor needs a :class:`Tkinter.Canvas` or a
  45   :class:`ScrolledCanvas` as argument.  It should be used when :mod:`turtle` is
  46   used as part of some application.
  47
  48   The function :func:`Screen` returns a singleton object of a
  49   :class:`TurtleScreen` subclass. This function should be used when
  50   :mod:`turtle` is used as a standalone tool for doing graphics.
  51   As a singleton object, inheriting from its class is not possible.
  52
  53   All methods of TurtleScreen/Screen also exist as functions, i.e. as part of
  54   the procedure-oriented interface.
  55
  562. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw
  57   on a :class:`TurtleScreen`.  Its constructor needs a Canvas, ScrolledCanvas
  58   or TurtleScreen as argument, so the RawTurtle objects know where to draw.
  59
  60   Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`),
  61   which draws on "the" :class:`Screen` - instance which is automatically
  62   created, if not already present.
  63
  64   All methods of RawTurtle/Turtle also exist as functions, i.e. part of the
  65   procedure-oriented interface.
  66
  67The procedural interface provides functions which are derived from the methods
  68of the classes :class:`Screen` and :class:`Turtle`.  They have the same names as
  69the corresponding methods.  A screen object is automatically created whenever a
  70function derived from a Screen method is called.  An (unnamed) turtle object is
  71automatically created whenever any of the functions derived from a Turtle method
  72is called.
  73
  74To use multiple turtles an a screen one has to use the object-oriented interface.
  75
  76.. note::
  77   In the following documentation the argument list for functions is given.
  78   Methods, of course, have the additional first argument *self* which is
  79   omitted here.
  80
  81
  82Overview over available Turtle and Screen methods
  83=================================================
  84
  85Turtle methods
  86--------------
  87
  88Turtle motion
  89   Move and draw
  90      | :func:`forward` | :func:`fd`
  91      | :func:`backward` | :func:`bk` | :func:`back`
  92      | :func:`right` | :func:`rt`
  93      | :func:`left` | :func:`lt`
  94      | :func:`goto` | :func:`setpos` | :func:`setposition`
  95      | :func:`setx`
  96      | :func:`sety`
  97      | :func:`setheading` | :func:`seth`
  98      | :func:`home`
  99      | :func:`circle`
 100      | :func:`dot`
 101      | :func:`stamp`
 102      | :func:`clearstamp`
 103      | :func:`clearstamps`
 104      | :func:`undo`
 105      | :func:`speed`
 106
 107   Tell Turtle's state
 108      | :func:`position` | :func:`pos`
 109      | :func:`towards`
 110      | :func:`xcor`
 111      | :func:`ycor`
 112      | :func:`heading`
 113      | :func:`distance`
 114
 115   Setting and measurement
 116      | :func:`degrees`
 117      | :func:`radians`
 118
 119Pen control
 120   Drawing state
 121      | :func:`pendown` | :func:`pd` | :func:`down`
 122      | :func:`penup` | :func:`pu` | :func:`up`
 123      | :func:`pensize` | :func:`width`
 124      | :func:`pen`
 125      | :func:`isdown`
 126
 127   Color control
 128      | :func:`color`
 129      | :func:`pencolor`
 130      | :func:`fillcolor`
 131
 132   Filling
 133      | :func:`fill`
 134      | :func:`begin_fill`
 135      | :func:`end_fill`
 136
 137   More drawing control
 138      | :func:`reset`
 139      | :func:`clear`
 140      | :func:`write`
 141
 142Turtle state
 143   Visibility
 144      | :func:`showturtle` | :func:`st`
 145      | :func:`hideturtle` | :func:`ht`
 146      | :func:`isvisible`
 147
 148   Appearance
 149      | :func:`shape`
 150      | :func:`resizemode`
 151      | :func:`shapesize` | :func:`turtlesize`
 152      | :func:`settiltangle`
 153      | :func:`tiltangle`
 154      | :func:`tilt`
 155
 156Using events
 157   | :func:`onclick`
 158   | :func:`onrelease`
 159   | :func:`ondrag`
 160
 161Special Turtle methods
 162   | :func:`begin_poly`
 163   | :func:`end_poly`
 164   | :func:`get_poly`
 165   | :func:`clone`
 166   | :func:`getturtle` | :func:`getpen`
 167   | :func:`getscreen`
 168   | :func:`setundobuffer`
 169   | :func:`undobufferentries`
 170   | :func:`tracer`
 171   | :func:`window_width`
 172   | :func:`window_height`
 173
 174
 175Methods of TurtleScreen/Screen
 176------------------------------
 177
 178Window control
 179   | :func:`bgcolor`
 180   | :func:`bgpic`
 181   | :func:`clear` | :func:`clearscreen`
 182   | :func:`reset` | :func:`resetscreen`
 183   | :func:`screensize`
 184   | :func:`setworldcoordinates`
 185
 186Animation control
 187   | :func:`delay`
 188   | :func:`tracer`
 189   | :func:`update`
 190
 191Using screen events
 192   | :func:`listen`
 193   | :func:`onkey`
 194   | :func:`onclick` | :func:`onscreenclick`
 195   | :func:`ontimer`
 196
 197Settings and special methods
 198   | :func:`mode`
 199   | :func:`colormode`
 200   | :func:`getcanvas`
 201   | :func:`getshapes`
 202   | :func:`register_shape` | :func:`addshape`
 203   | :func:`turtles`
 204   | :func:`window_height`
 205   | :func:`window_width`
 206
 207Methods specific to Screen
 208   | :func:`bye`
 209   | :func:`exitonclick`
 210   | :func:`setup`
 211   | :func:`title`
 212
 213
 214Methods of RawTurtle/Turtle and corresponding functions
 215=======================================================
 216
 217Most of the examples in this section refer to a Turtle instance called
 218``turtle``.
 219
 220Turtle motion
 221-------------
 222
 223.. function:: forward(distance)
 224              fd(distance)
 225
 226   :param distance: a number (integer or float)
 227
 228   Move the turtle forward by the specified *distance*, in the direction the
 229   turtle is headed.
 230
 231   .. doctest::
 232
 233      >>> turtle.position()
 234      (0.00,0.00)
 235      >>> turtle.forward(25)
 236      >>> turtle.position()
 237      (25.00,0.00)
 238      >>> turtle.forward(-75)
 239      >>> turtle.position()
 240      (-50.00,0.00)
 241
 242
 243.. function:: back(distance)
 244              bk(distance)
 245              backward(distance)
 246
 247   :param distance: a number
 248
 249   Move the turtle backward by *distance*, opposite to the direction the
 250   turtle is headed.  Do not change the turtle's heading.
 251
 252   .. doctest::
 253      :hide:
 254
 255      >>> turtle.goto(0, 0)
 256
 257   .. doctest::
 258
 259      >>> turtle.position()
 260      (0.00,0.00)
 261      >>> turtle.backward(30)
 262      >>> turtle.position()
 263      (-30.00,0.00)
 264
 265
 266.. function:: right(angle)
 267              rt(angle)
 268
 269   :param angle: a number (integer or float)
 270
 271   Turn turtle right by *angle* units.  (Units are by default degrees, but
 272   can be set via the :func:`degrees` and :func:`radians` functions.)  Angle
 273   orientation depends on the turtle mode, see :func:`mode`.
 274
 275   .. doctest::
 276      :hide:
 277
 278      >>> turtle.setheading(22)
 279
 280   .. doctest::
 281
 282      >>> turtle.heading()
 283      22.0
 284      >>> turtle.right(45)
 285      >>> turtle.heading()
 286      337.0
 287
 288
 289.. function:: left(angle)
 290              lt(angle)
 291
 292   :param angle: a number (integer or float)
 293
 294   Turn turtle left by *angle* units.  (Units are by default degrees, but
 295   can be set via the :func:`degrees` and :func:`radians` functions.)  Angle
 296   orientation depends on the turtle mode, see :func:`mode`.
 297
 298   .. doctest::
 299      :hide:
 300
 301      >>> turtle.setheading(22)
 302
 303   .. doctest::
 304
 305      >>> turtle.heading()
 306      22.0
 307      >>> turtle.left(45)
 308      >>> turtle.heading()
 309      67.0
 310
 311
 312.. function:: goto(x, y=None)
 313              setpos(x, y=None)
 314              setposition(x, y=None)
 315
 316   :param x: a number or a pair/vector of numbers
 317   :param y: a number or ``None``
 318
 319   If *y* is ``None``, *x* must be a pair of coordinates or a :class:`Vec2D`
 320   (e.g. as returned by :func:`pos`).
 321
 322   Move turtle to an absolute position.  If the pen is down, draw line.  Do
 323   not change the turtle's orientation.
 324
 325   .. doctest::
 326      :hide:
 327
 328      >>> turtle.goto(0, 0)
 329
 330   .. doctest::
 331
 332       >>> tp = turtle.pos()
 333       >>> tp
 334       (0.00,0.00)
 335       >>> turtle.setpos(60,30)
 336       >>> turtle.pos()
 337       (60.00,30.00)
 338       >>> turtle.setpos((20,80))
 339       >>> turtle.pos()
 340       (20.00,80.00)
 341       >>> turtle.setpos(tp)
 342       >>> turtle.pos()
 343       (0.00,0.00)
 344
 345
 346.. function:: setx(x)
 347
 348   :param x: a number (integer or float)
 349
 350   Set the turtle's first coordinate to *x*, leave second coordinate
 351   unchanged.
 352
 353   .. doctest::
 354      :hide:
 355
 356      >>> turtle.goto(0, 240)
 357
 358   .. doctest::
 359
 360      >>> turtle.position()
 361      (0.00,240.00)
 362      >>> turtle.setx(10)
 363      >>> turtle.position()
 364      (10.00,240.00)
 365
 366
 367.. function:: sety(y)
 368
 369   :param y: a number (integer or float)
 370
 371   Set the turtle's second coordinate to *y*, leave first coordinate unchanged.
 372
 373   .. doctest::
 374      :hide:
 375
 376      >>> turtle.goto(0, 40)
 377
 378   .. doctest::
 379
 380      >>> turtle.position()
 381      (0.00,40.00)
 382      >>> turtle.sety(-10)
 383      >>> turtle.position()
 384      (0.00,-10.00)
 385
 386
 387.. function:: setheading(to_angle)
 388              seth(to_angle)
 389
 390   :param to_angle: a number (integer or float)
 391
 392   Set the orientation of the turtle to *to_angle*.  Here are some common
 393   directions in degrees:
 394
 395   =================== ====================
 396    standard mode           logo mode
 397   =================== ====================
 398      0 - east                0 - north
 399     90 - north              90 - east
 400    180 - west              180 - south
 401    270 - south             270 - west
 402   =================== ====================
 403
 404   .. doctest::
 405
 406      >>> turtle.setheading(90)
 407      >>> turtle.heading()
 408      90.0
 409
 410
 411.. function:: home()
 412
 413   Move turtle to the origin -- coordinates (0,0) -- and set its heading to
 414   its start-orientation (which depends on the mode, see :func:`mode`).
 415
 416   .. doctest::
 417      :hide:
 418
 419      >>> turtle.setheading(90)
 420      >>> turtle.goto(0, -10)
 421
 422   .. doctest::
 423
 424      >>> turtle.heading()
 425      90.0
 426      >>> turtle.position()
 427      (0.00,-10.00)
 428      >>> turtle.home()
 429      >>> turtle.position()
 430      (0.00,0.00)
 431      >>> turtle.heading()
 432      0.0
 433
 434
 435.. function:: circle(radius, extent=None, steps=None)
 436
 437   :param radius: a number
 438   :param extent: a number (or ``None``)
 439   :param steps: an integer (or ``None``)
 440
 441   Draw a circle with given *radius*.  The center is *radius* units left of
 442   the turtle; *extent* -- an angle -- determines which part of the circle
 443   is drawn.  If *extent* is not given, draw the entire circle.  If *extent*
 444   is not a full circle, one endpoint of the arc is the current pen
 445   position.  Draw the arc in counterclockwise direction if *radius* is
 446   positive, otherwise in clockwise direction.  Finally the direction of the
 447   turtle is changed by the amount of *extent*.
 448
 449   As the circle is approximated by an inscribed regular polygon, *steps*
 450   determines the number of steps to use.  If not given, it will be
 451   calculated automatically.  May be used to draw regular polygons.
 452
 453   .. doctest::
 454
 455      >>> turtle.home()
 456      >>> turtle.position()
 457      (0.00,0.00)
 458      >>> turtle.heading()
 459      0.0
 460      >>> turtle.circle(50)
 461      >>> turtle.position()
 462      (-0.00,0.00)
 463      >>> turtle.heading()
 464      0.0
 465      >>> turtle.circle(120, 180)  # draw a semicircle
 466      >>> turtle.position()
 467      (0.00,240.00)
 468      >>> turtle.heading()
 469      180.0
 470
 471
 472.. function:: dot(size=None, *color)
 473
 474   :param size: an integer >= 1 (if given)
 475   :param color: a colorstring or a numeric color tuple
 476
 477   Draw a circular dot with diameter *size*, using *color*.  If *size* is
 478   not given, the maximum of pensize+4 and 2*pensize is used.
 479
 480
 481   .. doctest::
 482
 483      >>> turtle.home()
 484      >>> turtle.dot()
 485      >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
 486      >>> turtle.position()
 487      (100.00,-0.00)
 488      >>> turtle.heading()
 489      0.0
 490
 491
 492.. function:: stamp()
 493
 494   Stamp a copy of the turtle shape onto the canvas at the current turtle
 495   position.  Return a stamp_id for that stamp, which can be used to delete
 496   it by calling ``clearstamp(stamp_id)``.
 497
 498   .. doctest::
 499
 500      >>> turtle.color("blue")
 501      >>> turtle.stamp()
 502      11
 503      >>> turtle.fd(50)
 504
 505
 506.. function:: clearstamp(stampid)
 507
 508   :param stampid: an integer, must be return value of previous
 509                   :func:`stamp` call
 510
 511   Delete stamp with given *stampid*.
 512
 513   .. doctest::
 514
 515      >>> turtle.position()
 516      (150.00,-0.00)
 517      >>> turtle.color("blue")
 518      >>> astamp = turtle.stamp()
 519      >>> turtle.fd(50)
 520      >>> turtle.position()
 521      (200.00,-0.00)
 522      >>> turtle.clearstamp(astamp)
 523      >>> turtle.position()
 524      (200.00,-0.00)
 525
 526
 527.. function:: clearstamps(n=None)
 528
 529   :param n: an integer (or ``None``)
 530
 531   Delete all or first/last *n* of turtle's stamps.  If *n* is None, delete
 532   all stamps, if *n* > 0 delete first *n* stamps, else if *n* < 0 delete
 533   last *n* stamps.
 534
 535   .. doctest::
 536
 537      >>> for i in range(8):
 538      ...     turtle.stamp(); turtle.fd(30)
 539      13
 540      14
 541      15
 542      16
 543      17
 544      18
 545      19
 546      20
 547      >>> turtle.clearstamps(2)
 548      >>> turtle.clearstamps(-2)
 549      >>> turtle.clearstamps()
 550
 551
 552.. function:: undo()
 553
 554   Undo (repeatedly) the last turtle action(s).  Number of available
 555   undo actions is determined by the size of the undobuffer.
 556
 557   .. doctest::
 558
 559      >>> for i in range(4):
 560      ...     turtle.fd(50); turtle.lt(80)
 561      ...
 562      >>> for i in range(8):
 563      ...     turtle.undo()
 564
 565
 566.. function:: speed(speed=None)
 567
 568   :param speed: an integer in the range 0..10 or a speedstring (see below)
 569
 570   Set the turtle's speed to an integer value in the range 0..10.  If no
 571   argument is given, return current speed.
 572
 573   If input is a number greater than 10 or smaller than 0.5, speed is set
 574   to 0.  Speedstrings are mapped to speedvalues as follows:
 575
 576   * "fastest":  0
 577   * "fast":  10
 578   * "normal":  6
 579   * "slow":  3
 580   * "slowest":  1
 581
 582   Speeds from 1 to 10 enforce increasingly faster animation of line drawing
 583   and turtle turning.
 584
 585   Attention: *speed* = 0 means that *no* animation takes
 586   place. forward/back makes turtle jump and likewise left/right make the
 587   turtle turn instantly.
 588
 589   .. doctest::
 590
 591      >>> turtle.speed()
 592      3
 593      >>> turtle.speed('normal')
 594      >>> turtle.speed()
 595      6
 596      >>> turtle.speed(9)
 597      >>> turtle.speed()
 598      9
 599
 600
 601Tell Turtle's state
 602-------------------
 603
 604.. function:: position()
 605              pos()
 606
 607   Return the turtle's current location (x,y) (as a :class:`Vec2D` vector).
 608
 609   .. doctest::
 610
 611      >>> turtle.pos()
 612      (440.00,-0.00)
 613
 614
 615.. function:: towards(x, y=None)
 616
 617   :param x: a number or a pair/vector of numbers or a turtle instance
 618   :param y: a number if *x* is a number, else ``None``
 619
 620   Return the angle between the line from turtle position to position specified
 621   by (x,y), the vector or the other turtle.  This depends on the turtle's start
 622   orientation which depends on the mode - "standard"/"world" or "logo").
 623
 624   .. doctest::
 625
 626      >>> turtle.goto(10, 10)
 627      >>> turtle.towards(0,0)
 628      225.0
 629
 630
 631.. function:: xcor()
 632
 633   Return the turtle's x coordinate.
 634
 635   .. doctest::
 636
 637      >>> turtle.home()
 638      >>> turtle.left(50)
 639      >>> turtle.forward(100)
 640      >>> turtle.pos()
 641      (64.28,76.60)
 642      >>> print turtle.xcor()
 643      64.2787609687
 644
 645
 646.. function:: ycor()
 647
 648   Return the turtle's y coordinate.
 649
 650   .. doctest::
 651
 652      >>> turtle.home()
 653      >>> turtle.left(60)
 654      >>> turtle.forward(100)
 655      >>> print turtle.pos()
 656      (50.00,86.60)
 657      >>> print turtle.ycor()
 658      86.6025403784
 659
 660
 661.. function:: heading()
 662
 663   Return the turtle's current heading (value depends on the turtle mode, see
 664   :func:`mode`).
 665
 666   .. doctest::
 667
 668      >>> turtle.home()
 669      >>> turtle.left(67)
 670      >>> turtle.heading()
 671      67.0
 672
 673
 674.. function:: distance(x, y=None)
 675
 676   :param x: a number or a pair/vector of numbers or a turtle instance
 677   :param y: a number if *x* is a number, else ``None``
 678
 679   Return the distance from the turtle to (x,y), the given vector, or the given
 680   other turtle, in turtle step units.
 681
 682   .. doctest::
 683
 684      >>> turtle.home()
 685      >>> turtle.distance(30,40)
 686      50.0
 687      >>> turtle.distance((30,40))
 688      50.0
 689      >>> joe = Turtle()
 690      >>> joe.forward(77)
 691      >>> turtle.distance(joe)
 692      77.0
 693
 694
 695Settings for measurement
 696------------------------
 697
 698.. function:: degrees(fullcircle=360.0)
 699
 700   :param fullcircle: a number
 701
 702   Set angle measurement units, i.e. set number of "degrees" for a full circle.
 703   Default value is 360 degrees.
 704
 705   .. doctest::
 706
 707      >>> turtle.home()
 708      >>> turtle.left(90)
 709      >>> turtle.heading()
 710      90.0
 711      >>> turtle.degrees(400.0)  # angle measurement in gon
 712      >>> turtle.heading()
 713      100.0
 714      >>> turtle.degrees(360)
 715      >>> turtle.heading()
 716      90.0
 717
 718
 719.. function:: radians()
 720
 721   Set the angle measurement units to radians.  Equivalent to
 722   ``degrees(2*math.pi)``.
 723
 724   .. doctest::
 725
 726      >>> turtle.home()
 727      >>> turtle.left(90)
 728      >>> turtle.heading()
 729      90.0
 730      >>> turtle.radians()
 731      >>> turtle.heading()
 732      1.5707963267948966
 733
 734   .. doctest::
 735      :hide:
 736
 737      >>> turtle.degrees(360)
 738
 739
 740Pen control
 741-----------
 742
 743Drawing state
 744~~~~~~~~~~~~~
 745
 746.. function:: pendown()
 747              pd()
 748              down()
 749
 750   Pull the pen down -- drawing when moving.
 751
 752
 753.. function:: penup()
 754              pu()
 755              up()
 756
 757   Pull the pen up -- no drawing when moving.
 758
 759
 760.. function:: pensize(width=None)
 761              width(width=None)
 762
 763   :param width: a positive number
 764
 765   Set the line thickness to *width* or return it.  If resizemode is set to
 766   "auto" and turtleshape is a polygon, that polygon is drawn with the same line
 767   thickness.  If no argument is given, the current pensize is returned.
 768
 769   .. doctest::
 770
 771      >>> turtle.pensize()
 772      1
 773      >>> turtle.pensize(10)   # from here on lines of width 10 are drawn
 774
 775
 776.. function:: pen(pen=None, **pendict)
 777
 778   :param pen: a dictionary with some or all of the below listed keys
 779   :param pendict: one or more keyword-arguments with the below listed keys as keywords
 780
 781   Return or set the pen's attributes in a "pen-dictionary" with the following
 782   key/value pairs:
 783
 784   * "shown": True/False
 785   * "pendown": True/False
 786   * "pencolor": color-string or color-tuple
 787   * "fillcolor": color-string or color-tuple
 788   * "pensize": positive number
 789   * "speed": number in range 0..10
 790   * "resizemode": "auto" or "user" or "noresize"
 791   * "stretchfactor": (positive number, positive number)
 792   * "outline": positive number
 793   * "tilt": number
 794
 795   This dictionary can be used as argument for a subsequent call to :func:`pen`
 796   to restore the former pen-state.  Moreover one or more of these attributes
 797   can be provided as keyword-arguments.  This can be used to set several pen
 798   attributes in one statement.
 799
 800   .. doctest::
 801      :options: +NORMALIZE_WHITESPACE
 802
 803      >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
 804      >>> sorted(turtle.pen().items())
 805      [('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 806       ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 807       ('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
 808      >>> penstate=turtle.pen()
 809      >>> turtle.color("yellow", "")
 810      >>> turtle.penup()
 811      >>> sorted(turtle.pen().items())
 812      [('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow'),
 813       ('pendown', False), ('pensize', 10), ('resizemode', 'noresize'),
 814       ('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
 815      >>> turtle.pen(penstate, fillcolor="green")
 816      >>> sorted(turtle.pen().items())
 817      [('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red'),
 818       ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 819       ('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
 820
 821
 822.. function:: isdown()
 823
 824   Return ``True`` if pen is down, ``False`` if it's up.
 825
 826   .. doctest::
 827
 828      >>> turtle.penup()
 829      >>> turtle.isdown()
 830      False
 831      >>> turtle.pendown()
 832      >>> turtle.isdown()
 833      True
 834
 835
 836Color control
 837~~~~~~~~~~~~~
 838
 839.. function:: pencolor(*args)
 840
 841   Return or set the pencolor.
 842
 843   Four input formats are allowed:
 844
 845   ``pencolor()``
 846      Return the current pencolor as color specification string or
 847      as a tuple (see example).  May be used as input to another
 848      color/pencolor/fillcolor call.
 849
 850   ``pencolor(colorstring)``
 851      Set pencolor to *colorstring*, which is a Tk color specification string,
 852      such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
 853
 854   ``pencolor((r, g, b))``
 855      Set pencolor to the RGB color represented by the tuple of *r*, *g*, and
 856      *b*.  Each of *r*, *g*, and *b* must be in the range 0..colormode, where
 857      colormode is either 1.0 or 255 (see :func:`colormode`).
 858
 859   ``pencolor(r, g, b)``
 860      Set pencolor to the RGB color represented by *r*, *g*, and *b*.  Each of
 861      *r*, *g*, and *b* must be in the range 0..colormode.
 862
 863    If turtleshape is a polygon, the outline of that polygon is drawn with the
 864    newly set pencolor.
 865
 866   .. doctest::
 867
 868       >>> colormode()
 869       1.0
 870       >>> turtle.pencolor()
 871       'red'
 872       >>> turtle.pencolor("brown")
 873       >>> turtle.pencolor()
 874       'brown'
 875       >>> tup = (0.2, 0.8, 0.55)
 876       >>> turtle.pencolor(tup)
 877       >>> turtle.pencolor()
 878       (0.20000000000000001, 0.80000000000000004, 0.5490196078431373)
 879       >>> colormode(255)
 880       >>> turtle.pencolor()
 881       (51, 204, 140)
 882       >>> turtle.pencolor('#32c18f')
 883       >>> turtle.pencolor()
 884       (50, 193, 143)
 885
 886
 887.. function:: fillcolor(*args)
 888
 889   Return or set the fillcolor.
 890
 891   Four input formats are allowed:
 892
 893   ``fillcolor()``
 894      Return the current fillcolor as color specification string, possibly
 895      in tuple format (see example).  May be used as input to another
 896      color/pencolor/fillcolor call.
 897
 898   ``fillcolor(colorstring)``
 899      Set fillcolor to *colorstring*, which is a Tk color specification string,
 900      such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
 901
 902   ``fillcolor((r, g, b))``
 903      Set fillcolor to the RGB color represented by the tuple of *r*, *g*, and
 904      *b*.  Each of *r*, *g*, and *b* must be in the range 0..colormode, where
 905      colormode is either 1.0 or 255 (see :func:`colormode`).
 906
 907   ``fillcolor(r, g, b)``
 908      Set fillcolor to the RGB color represented by *r*, *g*, and *b*.  Each of
 909      *r*, *g*, and *b* must be in the range 0..colormode.
 910
 911    If turtleshape is a polygon, the interior of that polygon is drawn
 912    with the newly set fillcolor.
 913
 914   .. doctest::
 915
 916       >>> turtle.fillcolor("violet")
 917       >>> turtle.fillcolor()
 918       'violet'
 919       >>> col = turtle.pencolor()
 920       >>> col
 921       (50, 193, 143)
 922       >>> turtle.fillcolor(col)
 923       >>> turtle.fillcolor()
 924       (50, 193, 143)
 925       >>> turtle.fillcolor('#ffffff')
 926       >>> turtle.fillcolor()
 927       (255, 255, 255)
 928
 929
 930.. function:: color(*args)
 931
 932   Return or set pencolor and fillcolor.
 933
 934   Several input formats are allowed.  They use 0 to 3 arguments as
 935   follows:
 936
 937   ``color()``
 938      Return the current pencolor and the current fillcolor as a pair of color
 939      specification strings or tuples as returned by :func:`pencolor` and
 940      :func:`fillcolor`.
 941
 942   ``color(colorstring)``, ``color((r,g,b))``, ``color(r,g,b)``
 943      Inputs as in :func:`pencolor`, set both, fillcolor and pencolor, to the
 944      given value.
 945
 946   ``color(colorstring1, colorstring2)``, ``color((r1,g1,b1), (r2,g2,b2))``
 947      Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)``
 948      and analogously if the other input format is used.
 949
 950    If turtleshape is a polygon, outline and interior of that polygon is drawn
 951    with the newly set colors.
 952
 953   .. doctest::
 954
 955       >>> turtle.color("red", "green")
 956       >>> turtle.color()
 957       ('red', 'green')
 958       >>> color("#285078", "#a0c8f0")
 959       >>> color()
 960       ((40, 80, 120), (160, 200, 240))
 961
 962
 963See also: Screen method :func:`colormode`.
 964
 965
 966Filling
 967~~~~~~~
 968
 969.. doctest::
 970   :hide:
 971
 972   >>> turtle.home()
 973
 974.. function:: fill(flag)
 975
 976   :param flag: True/False (or 1/0 respectively)
 977
 978   Call ``fill(True)`` before drawing the shape you want to fill, and
 979   ``fill(False)`` when done.  When used without argument: return fillstate
 980   (``True`` if filling, ``False`` else).
 981
 982   .. doctest::
 983
 984      >>> turtle.fill(True)
 985      >>> for _ in range(3):
 986      ...    turtle.forward(100)
 987      ...    turtle.left(120)
 988      ...
 989      >>> turtle.fill(False)
 990
 991
 992.. function:: begin_fill()
 993
 994   Call just before drawing a shape to be filled.  Equivalent to ``fill(True)``.
 995
 996
 997.. function:: end_fill()
 998
 999   Fill the shape drawn after the last call to :func:`begin_fill`.  Equivalent
1000   to ``fill(False)``.
1001
1002   .. doctest::
1003
1004      >>> turtle.color("black", "red")
1005      >>> turtle.begin_fill()
1006      >>> turtle.circle(80)
1007      >>> turtle.end_fill()
1008
1009
1010More drawing control
1011~~~~~~~~~~~~~~~~~~~~
1012
1013.. function:: reset()
1014
1015   Delete the turtle's drawings from the screen, re-center the turtle and set
1016   variables to the default values.
1017
1018   .. doctest::
1019
1020      >>> turtle.goto(0,-22)
1021      >>> turtle.left(100)
1022      >>> turtle.position()
1023      (0.00,-22.00)
1024      >>> turtle.heading()
1025      100.0
1026      >>> turtle.reset()
1027      >>> turtle.position()
1028      (0.00,0.00)
1029      >>> turtle.heading()
1030      0.0
1031
1032
1033.. function:: clear()
1034
1035   Delete the turtle's drawings from the screen.  Do not move turtle.  State and
1036   position of the turtle as well as drawings of other turtles are not affected.
1037
1038
1039.. function:: write(arg, move=False, align="left", font=("Arial", 8, "normal"))
1040
1041   :param arg: object to be written to the TurtleScreen
1042   :param move: True/False
1043   :param align: one of the strings "left", "center" or right"
1044   :param font: a triple (fontname, fontsize, fonttype)
1045
1046   Write text - the string representation of *arg* - at the current turtle
1047   position according to *align* ("left", "center" or right") and with the given
1048   font.  If *move* is True, the pen is moved to the bottom-right corner of the
1049   text.  By default, *move* is False.
1050
1051   >>> turtle.write("Home = ", True, align="center")
1052   >>> turtle.write((0,0), True)
1053
1054
1055Turtle state
1056------------
1057
1058Visibility
1059~~~~~~~~~~
1060
1061.. function:: hideturtle()
1062              ht()
1063
1064   Make the turtle invisible.  It's a good idea to do this while you're in the
1065   middle of doing some complex drawing, because hiding the turtle speeds up the
1066   drawing observably.
1067
1068   .. doctest::
1069
1070      >>> turtle.hideturtle()
1071
1072
1073.. function:: showturtle()
1074              st()
1075
1076   Make the turtle visible.
1077
1078   .. doctest::
1079
1080      >>> turtle.showturtle()
1081
1082
1083.. function:: isvisible()
1084
1085   Return True if the Turtle is shown, False if it's hidden.
1086
1087   >>> turtle.hideturtle()
1088   >>> turtle.isvisible()
1089   False
1090   >>> turtle.showturtle()
1091   >>> turtle.isvisible()
1092   True
1093
1094
1095Appearance
1096~~~~~~~~~~
1097
1098.. function:: shape(name=None)
1099
1100   :param name: a string which is a valid shapename
1101
1102   Set turtle shape to shape with given *name* or, if name is not given, return
1103   name of current shape.  Shape with *name* must exist in the TurtleScreen's
1104   shape dictionary.  Initially there are the following polygon shapes: "arrow",
1105   "turtle", "circle", "square", "triangle", "classic".  To learn about how to
1106   deal with shapes see Screen method :func:`register_shape`.
1107
1108   .. doctest::
1109
1110      >>> turtle.shape()
1111      'classic'
1112      >>> turtle.shape("turtle")
1113      >>> turtle.shape()
1114      'turtle'
1115
1116
1117.. function:: resizemode(rmode=None)
1118
1119   :param rmode: one of the strings "auto", "user", "noresize"
1120
1121   Set resizemode to one of the values: "auto", "user", "noresize".  If *rmode*
1122   is not given, return current resizemode.  Different resizemodes have the
1123   following effects:
1124
1125   - "auto": adapts the appearance of the turtle corresponding to the value of pensize.
1126   - "user": adapts the appearance of the turtle according to the values of
1127     stretchfactor and outlinewidth (outline), which are set by
1128     :func:`shapesize`.
1129   - "noresize": no adaption of the turtle's appearance takes place.
1130
1131   resizemode("user") is called by :func:`shapesize` when used with arguments.
1132
1133   .. doctest::
1134
1135      >>> turtle.resizemode()
1136      'noresize'
1137      >>> turtle.resizemode("auto")
1138      >>> turtle.resizemode()
1139      'auto'
1140
1141
1142.. function:: shapesize(stretch_wid=None, stretch_len=None, outline=None)
1143              turtlesize(stretch_wid=None, stretch_len=None, outline=None)
1144
1145   :param stretch_wid: positive number
1146   :param stretch_len: positive number
1147   :param outline: positive number
1148
1149   Return or set the pen's attributes x/y-stretchfactors and/or outline.  Set
1150   resizemode to "user".  If and only if resizemode is set to "user", the turtle
1151   will be displayed stretched according to its stretchfactors: *stretch_wid* is
1152   stretchfactor perpendicular to its orientation, *stretch_len* is
1153   stretchfactor in direction of its orientation, *outline* determines the width
1154   of the shapes's outline.
1155
1156   .. doctest::
1157
1158      >>> turtle.shapesize()
1159      (1, 1, 1)
1160      >>> turtle.resizemode("user")
1161      >>> turtle.shapesize(5, 5, 12)
1162      >>> turtle.shapesize()
1163      (5, 5, 12)
1164      >>> turtle.shapesize(outline=8)
1165      >>> turtle.shapesize()
1166      (5, 5, 8)
1167
1168
1169.. function:: tilt(angle)
1170
1171   :param angle: a number
1172
1173   Rotate the turtleshape by *angle* from its current tilt-angle, but do *not*
1174   change the turtle's heading (direction of movement).
1175
1176   .. doctest::
1177
1178      >>> turtle.reset()
1179      >>> turtle.shape("circle")
1180      >>> turtle.shapesize(5,2)
1181      >>> turtle.tilt(30)
1182      >>> turtle.fd(50)
1183      >>> turtle.tilt(30)
1184      >>> turtle.fd(50)
1185
1186
1187.. function:: settiltangle(angle)
1188
1189   :param angle: a number
1190
1191   Rotate the turtleshape to point in the direction specified by *angle*,
1192   regardless of its current tilt-angle.  *Do not* change the turtle's heading
1193   (direction of movement).
1194
1195   .. doctest::
1196
1197      >>> turtle.reset()
1198      >>> turtle.shape("circle")
1199      >>> turtle.shapesize(5,2)
1200      >>> turtle.settiltangle(45)
1201      >>> turtle.fd(50)
1202      >>> turtle.settiltangle(-45)
1203      >>> turtle.fd(50)
1204
1205
1206.. function:: tiltangle()
1207
1208   Return the current tilt-angle, i.e. the angle between the orientation of the
1209   turtleshape and the heading of the turtle (its direction of movement).
1210
1211   .. doctest::
1212
1213      >>> turtle.reset()
1214      >>> turtle.shape("circle")
1215      >>> turtle.shapesize(5,2)
1216      >>> turtle.tilt(45)
1217      >>> turtle.tiltangle()
1218      45.0
1219
1220
1221Using events
1222------------
1223
1224.. function:: onclick(fun, btn=1, add=None)
1225
1226   :param fun: a function with two arguments which will be called with the
1227               coordinates of the clicked point on the canvas
1228   :param num: number of the mouse-button, defaults to 1 (left mouse button)
1229   :param add: ``True`` or ``False`` -- if ``True``, a new binding will be
1230               added, otherwise it will replace a former binding
1231
1232   Bind *fun* to mouse-click events on this turtle.  If *fun* is ``None``,
1233   existing bindings are removed.  Example for the anonymous turtle, i.e. the
1234   procedural way:
1235
1236   .. doctest::
1237
1238      >>> def turn(x, y):
1239      ...     left(180)
1240      ...
1241      >>> onclick(turn)  # Now clicking into the turtle will turn it.
1242      >>> onclick(None)  # event-binding will be removed
1243
1244
1245.. function:: onrelease(fun, btn=1, add=None)
1246
1247   :param fun: a function with two arguments which will be called with the
1248               coordinates of the clicked point on the canvas
1249   :param num: number of the mouse-button, defaults to 1 (left mouse button)
1250   :param add: ``True`` or ``False`` -- if ``True``, a new binding will be
1251               added, otherwise it will replace a former binding
1252
1253   Bind *fun* to mouse-button-release events on this turtle.  If *fun* is
1254   ``None``, existing bindings are removed.
1255
1256   .. doctest::
1257
1258      >>> class MyTurtle(Turtle):
1259      ...     def glow(self,x,y):
1260      ...         self.fillcolor("red")
1261      ...     def unglow(self,x,y):
1262      ...         self.fillcolor("")
1263      ...
1264      >>> turtle = MyTurtle()
1265      >>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,
1266      >>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.
1267
1268
1269.. function:: ondrag(fun, btn=1, add=None)
1270
1271   :param fun: a function with two arguments which will be called with the
1272               coordinates of the clicked point on the canvas
1273   :param num: number of the mouse-button, defaults to 1 (left mouse button)
1274   :param add: ``True`` or ``False`` -- if ``True``, a new binding will be
1275               added, otherwise it will replace a former binding
1276
1277   Bind *fun* to mouse-move events on this turtle.  If *fun* is ``None``,
1278   existing bindings are removed.
1279
1280   Remark: Every sequence of mouse-move-events on a turtle is preceded by a
1281   mouse-click event on that turtle.
1282
1283   .. doctest::
1284
1285      >>> turtle.ondrag(turtle.goto)
1286
1287   Subsequently, clicking and dragging the Turtle will move it across
1288   the screen thereby producing handdrawings (if pen is down).
1289
1290
1291Special Turtle methods
1292----------------------
1293
1294.. function:: begin_poly()
1295
1296   Start recording the vertices of a polygon.  Current turtle position is first
1297   vertex of polygon.
1298
1299
1300.. function:: end_poly()
1301
1302   Stop recording the vertices of a polygon.  Current turtle position is last
1303   vertex of polygon.  This will be connected with the first vertex.
1304
1305
1306.. function:: get_poly()
1307
1308   Return the last recorded polygon.
1309
1310   .. doctest::
1311
1312      >>> turtle.home()
1313      >>> turtle.begin_poly()
1314      >>> turtle.fd(100)
1315      >>> turtle.left(20)
1316      >>> turtle.fd(30)
1317      >>> turtle.left(60)
1318      >>> turtle.fd(50)
1319      >>> turtle.end_poly()
1320      >>> p = turtle.get_poly()
1321      >>> register_shape("myFavouriteShape", p)
1322
1323
1324.. function:: clone()
1325
1326   Create and return a clone of the turtle with same position, heading and
1327   turtle properties.
1328
1329   .. doctest::
1330
1331      >>> mick = Turtle()
1332      >>> joe = mick.clone()
1333
1334
1335.. function:: getturtle()
1336              getpen()
1337
1338   Return the Turtle object itself.  Only reasonable use: as a function to
1339   return the "anonymous turtle":
1340
1341   .. doctest::
1342
1343      >>> pet = getturtle()
1344      >>> pet.fd(50)
1345      >>> pet
1346      <turtle.Turtle object at 0x...>
1347
1348
1349.. function:: getscreen()
1350
1351   Return the :class:`TurtleScreen` object the turtle is drawing on.
1352   TurtleScreen methods can then be called for that object.
1353
1354   .. doctest::
1355
1356      >>> ts = turtle.getscreen()
1357      >>> ts
1358      <turtle._Screen object at 0x...>
1359      >>> ts.bgcolor("pink")
1360
1361
1362.. function:: setundobuffer(size)
1363
1364   :param size: an integer or ``None``
1365
1366   Set or disable undobuffer.  If *size* is an integer an empty undobuffer of
1367   given size is installed.  *size* gives the maximum number of turtle actions
1368   that can be undone by the :func:`undo` method/function.  If *size* is
1369   ``None``, the undobuffer is disabled.
1370
1371   .. doctest::
1372
1373      >>> turtle.setundobuffer(42)
1374
1375
1376.. function:: undobufferentries()
1377
1378   Return number of entries in the undobuffer.
1379
1380   .. doctest::
1381
1382      >>> while undobufferentries():
1383      ...     undo()
1384
1385
1386.. function:: tracer(flag=None, delay=None)
1387
1388   A replica of the corresponding TurtleScreen method.
1389
1390   .. deprecated:: 2.6
1391
1392
1393.. function:: window_width()
1394              window_height()
1395
1396   Both are replicas of the corresponding TurtleScreen methods.
1397
1398   .. deprecated:: 2.6
1399
1400
1401.. _compoundshapes:
1402
1403Excursus about the use of compound shapes
1404-----------------------------------------
1405
1406To use compound turtle shapes, which consist of several polygons of different
1407color, you must use the helper class :class:`Shape` explicitly as described
1408below:
1409
14101. Create an empty Shape object of type "compound".
14112. Add as many components to this object as desired, using the
1412   :meth:`addcomponent` method.
1413
1414   For example:
1415
1416   .. doctest::
1417
1418      >>> s = Shape("compound")
1419      >>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
1420      >>> s.addcomponent(poly1, "red", "blue")
1421      >>> poly2 = ((0,0),(10,-5),(-10,-5))
1422      >>> s.addcomponent(poly2, "blue", "red")
1423
14243. Now add the Shape to the Screen's shapelist and use it:
1425
1426   .. doctest::
1427
1428      >>> register_shape("myshape", s)
1429      >>> shape("myshape")
1430
1431
1432.. note::
1433
1434   The :class:`Shape` class is used internally by the :func:`register_shape`
1435   method in different ways.  The application programmer has to deal with the
1436   Shape class *only* when using compound shapes like shown above!
1437
1438
1439Methods of TurtleScreen/Screen and corresponding functions
1440==========================================================
1441
1442Most of the examples in this section refer to a TurtleScreen instance called
1443``screen``.
1444
1445.. doctest::
1446   :hide:
1447
1448   >>> screen = Screen()
1449
1450Window control
1451--------------
1452
1453.. function:: bgcolor(*args)
1454
1455   :param args: a color string or three numbers in the range 0..colormode or a
1456                3-tuple of such numbers
1457
1458   Set or return background color of the TurtleScreen.
1459
1460   .. doctest::
1461
1462      >>> screen.bgcolor("orange")
1463      >>> screen.bgcolor()
1464      'orange'
1465      >>> screen.bgcolor("#800080")
1466      >>> screen.bgcolor()
1467      (128, 0, 128)
1468
1469
1470.. function:: bgpic(picname=None)
1471
1472   :param picname: a string, name of a gif-file or ``"nopic"``, or ``None``
1473
1474   Set background image or return name of current backgroundimage.  If *picname*
1475   is a filename, set the corresponding image as background.  If *picname* is
1476   ``"nopic"``, delete background image, if present.  If *picname* is ``None``,
1477   return the filename of the current backgroundimage. ::
1478
1479       >>> screen.bgpic()
1480       'nopic'
1481       >>> screen.bgpic("landscape.gif")
1482       >>> screen.bgpic()
1483       "landscape.gif"
1484
1485
1486.. function:: clear()
1487              clearscreen()
1488
1489   Delete all drawings and all turtles from the TurtleScreen.  Reset the now
1490   empty TurtleScreen to its initial state: white background, no background
1491   image, no event bindings and tracing on.
1492
1493   .. note::
1494      This TurtleScreen method is available as a global function only under the
1495      name ``clearscreen``.  The global function ``clear`` is another one
1496      derived from the Turtle method ``clear``.
1497
1498
1499.. function:: reset()
1500              resetscreen()
1501
1502   Reset all Turtles on the Screen to their initial state.
1503
1504   .. note::
1505      This TurtleScreen method is available as a global function only under the
1506      name ``resetscreen``.  The global function ``reset`` is another one
1507      derived from the Turtle method ``reset``.
1508
1509
1510.. function:: screensize(canvwidth=None, canvheight=None, bg=None)
1511
1512   :param canvwidth: positive integer, new width of canvas in pixels
1513   :param canvheight: positive integer, new height of canvas in pixels
1514   :param bg: colorstring or color-tuple, new background color
1515
1516   If no arguments are given, return current (canvaswidth, canvasheight).  Else
1517   resize the canvas the turtles are drawing on.  Do not alter the drawing
1518   window.  To observe hidden parts of the canvas, use the scrollbars. With this
1519   method, one can make visible those parts of a drawing which were outside the
1520   canvas before.
1521
1522      >>> screen.screensize()
1523      (400, 300)
1524      >>> screen.screensize(2000,1500)
1525      >>> screen.screensize()
1526      (2000, 1500)
1527
1528   e.g. to search for an erroneously escaped turtle ;-)
1529
1530
1531.. function:: setworldcoordinates(llx, lly, urx, ury)
1532
1533   :param llx: a number, x-coordinate of lower left corner of canvas
1534   :param lly: a number, y-coordinate of lower left corner of canvas
1535   :param urx: a number, x-coordinate of upper right corner of canvas
1536   :param ury: a number, y-coordinate of upper right corner of canvas
1537
1538   Set up user-defined coordinate system and switch to mode "world" if
1539   necessary.  This performs a ``screen.reset()``.  If mode "world" is already
1540   active, all drawings are redrawn according to the new coordinates.
1541
1542   **ATTENTION**: in user-defined coordinate systems angles may appear
1543   distorted.
1544
1545   .. doctest::
1546
1547      >>> screen.reset()
1548      >>> screen.setworldcoordinates(-50,-7.5,50,7.5)
1549      >>> for _ in range(72):
1550      ...     left(10)
1551      ...
1552      >>> for _ in range(8):
1553      ...     left(45); fd(2)   # a regular octagon
1554
1555   .. doctest::
1556      :hide:
1557
1558      >>> screen.reset()
1559      >>> for t in turtles():
1560      ...      t.reset()
1561
1562
1563Animation control
1564-----------------
1565
1566.. function:: delay(delay=None)
1567
1568   :param delay: positive integer
1569
1570   Set or return the drawing *delay* in milliseconds.  (This is approximately
1571   the time interval between two consecutive canvas updates.)  The longer the
1572   drawing delay, the slower the animation.
1573
1574   Optional argument:
1575
1576   .. doctest::
1577
1578      >>> screen.delay()
1579      10
1580      >>> screen.delay(5)
1581      >>> screen.delay()
1582      5
1583
1584
1585.. function:: tracer(n=None, delay=None)
1586
1587   :param n: nonnegative integer
1588   :param delay: nonnegative integer
1589
1590   Turn turtle animation on/off and set delay for update drawings.  If *n* is
1591   given, only each n-th regular screen update is really performed.  (Can be
1592   used to accelerate the drawing of complex graphics.)  Second argument sets
1593   delay value (see :func:`delay`).
1594
1595   .. doctest::
1596
1597      >>> screen.tracer(8, 25)
1598      >>> dist = 2
1599      >>> for i in range(200):
1600      ...     fd(dist)
1601      ...     rt(90)
1602      ...     dist += 2
1603
1604
1605.. function:: update()
1606
1607   Perform a TurtleScreen update. To be used when tracer is turned off.
1608
1609See also the RawTurtle/Turtle method :func:`speed`.
1610
1611
1612Using screen events
1613-------------------
1614
1615.. function:: listen(xdummy=None, ydummy=None)
1616
1617   Set focus on TurtleScreen (in order to collect key-events).  Dummy arguments
1618   are provided in order to be able to pass :func:`listen` to the onclick method.
1619
1620
1621.. function:: onkey(fun, key)
1622
1623   :param fun: a function with no arguments or ``None``
1624   :param key: a string: key (e.g. "a") or key-symbol (e.g. "space")
1625
1626   Bind *fun* to key-release event of key.  If *fun* is ``None``, event bindings
1627   are removed. Remark: in order to be able to register key-events, TurtleScreen
1628   must have the focus. (See method :func:`listen`.)
1629
1630   .. doctest::
1631
1632      >>> def f():
1633      ...     fd(50)
1634      ...     lt(60)
1635      ...
1636      >>> screen.onkey(f, "Up")
1637      >>> screen.listen()
1638
1639
1640.. function:: onclick(fun, btn=1, add=None)
1641              onscreenclick(fun, btn=1, add=None)
1642
1643   :param fun: a function with two arguments which will be called with the
1644               coordinates of the clicked point on the canvas
1645   :param num: number of the mouse-button, defaults to 1 (left mouse button)
1646   :param add: ``True`` or ``False`` -- if ``True``, a new binding will be
1647               added, otherwise it will replace a former binding
1648
1649   Bind *fun* to mouse-click events on this screen.  If *fun* is ``None``,
1650   existing bindings are removed.
1651
1652   Example for a TurtleScreen instance named ``screen`` and a Turtle instance
1653   named turtle:
1654
1655   .. doctest::
1656
1657      >>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
1658      >>>                             # make the turtle move to the clicked point.
1659      >>> screen.onclick(None)        # remove event binding again
1660
1661   .. note::
1662      This TurtleScreen method is available as a global function only under the
1663      name ``onscreenclick``.  The global function ``onclick`` is another one
1664      derived from the Turtle method ``onclick``.
1665
1666
1667.. function:: ontimer(fun, t=0)
1668
1669   :param fun: a function with no arguments
1670   :param t: a number >= 0
1671
1672   Install a timer that calls *fun* after *t* milliseconds.
1673
1674   .. doctest::
1675
1676      >>> running = True
1677      >>> def f():
1678      ...     if running:
1679      ...         fd(50)
1680      ...         lt(60)
1681      ...         screen.ontimer(f, 250)
1682      >>> f()   ### makes the turtle march around
1683      >>> running = False
1684
1685
1686Settings and special methods
1687----------------------------
1688
1689.. function:: mode(mode=None)
1690
1691   :param mode: one of the strings "standard", "logo" or "world"
1692
1693   Set turtle mode ("standard", "logo" or "world") and perform reset.  If mode
1694   is not given, current mode is returned.
1695
1696   Mode "standard" is compatible with old :mod:`turtle`.  Mode "logo" is
1697   compatible with most Logo turtle graphics.  Mode "world" uses user-defined
1698   "world coordinates". **Attention**: in this mode angles appear distorted if
1699   ``x/y`` unit-ratio doesn't equal 1.
1700
1701   ============ ========================= ===================
1702       Mode      Initial turtle heading     positive angles
1703   ============ ========================= ===================
1704    "standard"    to the right (east)       counterclockwise
1705      "logo"        upward    (north)         clockwise
1706   ============ ========================= ===================
1707
1708   .. doctest::
1709
1710      >>> mode("logo")   # resets turtle heading to north
1711      >>> mode()
1712      'logo'
1713
1714
1715.. function:: colormode(cmode=None)
1716
1717   :param cmode: one of the values 1.0 or 255
1718
1719   Return the colormode or set it to 1.0 or 255.  Subsequently *r*, *g*, *b*
1720   values of color triples have to be in the range 0..\ *cmode*.
1721
1722   .. doctest::
1723
1724      >>> screen.colormode(1)
1725      >>> turtle.pencolor(240, 160, 80)
1726      Traceback (most recent call last):
1727           ...
1728      TurtleGraphicsError: bad color sequence: (240, 160, 80)
1729      >>> screen.colormode()
1730      1.0
1731      >>> screen.colormode(255)
1732      >>> screen.colormode()
1733      255
1734      >>> turtle.pencolor(240,160,80)
1735
1736
1737.. function:: getcanvas()
1738
1739   Return the Canvas of this TurtleScreen.  Useful for insiders who know what to
1740   do with a Tkinter Canvas.
1741
1742   .. doctest::
1743
1744      >>> cv = screen.getcanvas()
1745      >>> cv
1746      <turtle.ScrolledCanvas instance at 0x...>
1747
1748
1749.. function:: getshapes()
1750
1751   Return a list of names of all currently available turtle shapes.
1752
1753   .. doctest::
1754
1755      >>> screen.getshapes()
1756      ['arrow', 'blank', 'circle', ..., 'turtle']
1757
1758
1759.. function:: register_shape(name, shape=None)
1760              addshape(name, shape=None)
1761
1762   There are three different ways to call this function:
1763
1764   (1) *name* is the name of a gif-file and *shape* is ``None``: Install the
1765       corresponding image shape. ::
1766
1767       >>> screen.register_shape("turtle.gif")
1768
1769       .. note::
1770          Image shapes *do not* rotate when turning the turtle, so they do not
1771          display the heading of the turtle!
1772
1773   (2) *name* is an arbitrary string and *shape* is a tuple of pairs of
1774       coordinates: Install the corresponding polygon shape.
1775
1776       .. doctest::
1777
1778          >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
1779
1780   (3) *name* is an arbitrary string and shape is a (compound) :class:`Shape`
1781       object: Install the corresponding compound shape.
1782
1783   Add a turtle shape to TurtleScreen's shapelist.  Only thusly registered
1784   shapes can be used by issuing the command ``shape(shapename)``.
1785
1786
1787.. function:: turtles()
1788
1789   Return the list of turtles on the screen.
1790
1791   .. doctest::
1792
1793      >>> for turtle in screen.turtles():
1794      ...     turtle.color("red")
1795
1796
1797.. function:: window_height()
1798
1799   Return the height of the turtle window. ::
1800
1801       >>> screen.window_height()
1802       480
1803
1804
1805.. function:: window_width()
1806
1807   Return the width of the turtle window. ::
1808
1809       >>> screen.window_width()
1810       640
1811
1812
1813.. _screenspecific:
1814
1815Methods specific to Screen, not inherited from TurtleScreen
1816-----------------------------------------------------------
1817
1818.. function:: bye()
1819
1820   Shut the turtlegraphics window.
1821
1822
1823.. function:: exitonclick()
1824
1825   Bind bye() method to mouse clicks on the Screen.
1826
1827
1828   If the value "using_IDLE" in the configuration dictionary is ``False``
1829   (default value), also enter mainloop.  Remark: If IDLE with the ``-n`` switch
1830   (no subprocess) is used, this value should be set to ``True`` in
1831   :file:`turtle.cfg`.  In this case IDLE's own mainloop is active also for the
1832   client script.
1833
1834
1835.. function:: setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"])
1836
1837   Set the size and position of the main window.  Default values of arguments
1838   are stored in the configuration dicionary and can be changed via a
1839   :file:`turtle.cfg` file.
1840
1841   :param width: if an integer, a size in pixels, if a float, a fraction of the
1842                 screen; default is 50% of screen
1843   :param height: if an integer, the height in pixels, if a float, a fraction of
1844                  the screen; default is 75% of screen
1845   :param startx: if positive, starting position in pixels from the left
1846                  edge of the screen, if negative from the right edge, if None,
1847                  center window horizontally
1848   :param startx: if positive, starting position in pixels from the top
1849                  edge of the screen, if negative from the bottom edge, if None,
1850                  center window vertically
1851
1852   .. doctest::
1853
1854      >>> screen.setup (width=200, height=200, startx=0, starty=0)
1855      >>>              # sets window to 200x200 pixels, in upper left of screen
1856      >>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
1857      >>>              # sets window to 75% of screen by …

Large files files are truncated, but you can click here to view the full file