1================================= 2:mod:`turtle` --- Turtle graphics 3================================= 4 5.. module:: turtle 6 :synopsis: An educational framework for simple graphics applications 7 8.. sectionauthor:: Gregor Lingl <gregor.lingl@aon.at> 9 10**Source code:** :source:`Lib/turtle.py` 11 12.. testsetup:: default 13 14 from turtle import * 15 turtle = Turtle() 16 17-------------- 18 19Introduction 20============ 21 22Turtle graphics is a popular way for introducing programming to kids. It was 23part of the original Logo programming language developed by Wally Feurzeig, 24Seymour Papert and Cynthia Solomon in 1967. 25 26Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the 27command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the 28direction it is facing, drawing a line as it moves. Give it the command 29``turtle.right(25)``, and it rotates in-place 25 degrees clockwise. 30 31.. sidebar:: Turtle star 32 33 Turtle can draw intricate shapes using programs that repeat simple 34 moves. 35 36 .. image:: turtle-star.* 37 :align: center 38 39 .. literalinclude:: ../includes/turtle-star.py 40 41By combining together these and similar commands, intricate shapes and pictures 42can easily be drawn. 43 44The :mod:`turtle` module is an extended reimplementation of the same-named 45module from the Python standard distribution up to version Python 2.5. 46 47It tries to keep the merits of the old turtle module and to be (nearly) 100% 48compatible with it. This means in the first place to enable the learning 49programmer to use all the commands, classes and methods interactively when using 50the module from within IDLE run with the ``-n`` switch. 51 52The turtle module provides turtle graphics primitives, in both object-oriented 53and procedure-oriented ways. Because it uses :mod:`tkinter` for the underlying 54graphics, it needs a version of Python installed with Tk support. 55 56The object-oriented interface uses essentially two+two classes: 57 581. The :class:`TurtleScreen` class defines graphics windows as a playground for 59 the drawing turtles. Its constructor needs a :class:`tkinter.Canvas` or a 60 :class:`ScrolledCanvas` as argument. It should be used when :mod:`turtle` is 61 used as part of some application. 62 63 The function :func:`Screen` returns a singleton object of a 64 :class:`TurtleScreen` subclass. This function should be used when 65 :mod:`turtle` is used as a standalone tool for doing graphics. 66 As a singleton object, inheriting from its class is not possible. 67 68 All methods of TurtleScreen/Screen also exist as functions, i.e. as part of 69 the procedure-oriented interface. 70 712. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw 72 on a :class:`TurtleScreen`. Its constructor needs a Canvas, ScrolledCanvas 73 or TurtleScreen as argument, so the RawTurtle objects know where to draw. 74 75 Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`), 76 which draws on "the" :class:`Screen` instance which is automatically 77 created, if not already present. 78 79 All methods of RawTurtle/Turtle also exist as functions, i.e. part of the 80 procedure-oriented interface. 81 82The procedural interface provides functions which are derived from the methods 83of the classes :class:`Screen` and :class:`Turtle`. They have the same names as 84the corresponding methods. A screen object is automatically created whenever a 85function derived from a Screen method is called. An (unnamed) turtle object is 86automatically created whenever any of the functions derived from a Turtle method 87is called. 88 89To use multiple turtles on a screen one has to use the object-oriented interface. 90 91.. note:: 92 In the following documentation the argument list for functions is given. 93 Methods, of course, have the additional first argument *self* which is 94 omitted here. 95 96 97Overview of available Turtle and Screen methods 98================================================= 99 100Turtle methods 101-------------- 102 103Turtle motion 104 Move and draw 105 | :func:`forward` | :func:`fd` 106 | :func:`backward` | :func:`bk` | :func:`back` 107 | :func:`right` | :func:`rt` 108 | :func:`left` | :func:`lt` 109 | :func:`goto` | :func:`setpos` | :func:`setposition` 110 | :func:`setx` 111 | :func:`sety` 112 | :func:`setheading` | :func:`seth` 113 | :func:`home` 114 | :func:`circle` 115 | :func:`dot` 116 | :func:`stamp` 117 | :func:`clearstamp` 118 | :func:`clearstamps` 119 | :func:`undo` 120 | :func:`speed` 121 122 Tell Turtle's state 123 | :func:`position` | :func:`pos` 124 | :func:`towards` 125 | :func:`xcor` 126 | :func:`ycor` 127 | :func:`heading` 128 | :func:`distance` 129 130 Setting and measurement 131 | :func:`degrees` 132 | :func:`radians` 133 134Pen control 135 Drawing state 136 | :func:`pendown` | :func:`pd` | :func:`down` 137 | :func:`penup` | :func:`pu` | :func:`up` 138 | :func:`pensize` | :func:`width` 139 | :func:`pen` 140 | :func:`isdown` 141 142 Color control 143 | :func:`color` 144 | :func:`pencolor` 145 | :func:`fillcolor` 146 147 Filling 148 | :func:`filling` 149 | :func:`begin_fill` 150 | :func:`end_fill` 151 152 More drawing control 153 | :func:`reset` 154 | :func:`clear` 155 | :func:`write` 156 157Turtle state 158 Visibility 159 | :func:`showturtle` | :func:`st` 160 | :func:`hideturtle` | :func:`ht` 161 | :func:`isvisible` 162 163 Appearance 164 | :func:`shape` 165 | :func:`resizemode` 166 | :func:`shapesize` | :func:`turtlesize` 167 | :func:`shearfactor` 168 | :func:`settiltangle` 169 | :func:`tiltangle` 170 | :func:`tilt` 171 | :func:`shapetransform` 172 | :func:`get_shapepoly` 173 174Using events 175 | :func:`onclick` 176 | :func:`onrelease` 177 | :func:`ondrag` 178 179Special Turtle methods 180 | :func:`begin_poly` 181 | :func:`end_poly` 182 | :func:`get_poly` 183 | :func:`clone` 184 | :func:`getturtle` | :func:`getpen` 185 | :func:`getscreen` 186 | :func:`setundobuffer` 187 | :func:`undobufferentries` 188 189 190Methods of TurtleScreen/Screen 191------------------------------ 192 193Window control 194 | :func:`bgcolor` 195 | :func:`bgpic` 196 | :func:`clear` | :func:`clearscreen` 197 | :func:`reset` | :func:`resetscreen` 198 | :func:`screensize` 199 | :func:`setworldcoordinates` 200 201Animation control 202 | :func:`delay` 203 | :func:`tracer` 204 | :func:`update` 205 206Using screen events 207 | :func:`listen` 208 | :func:`onkey` | :func:`onkeyrelease` 209 | :func:`onkeypress` 210 | :func:`onclick` | :func:`onscreenclick` 211 | :func:`ontimer` 212 | :func:`mainloop` | :func:`done` 213 214Settings and special methods 215 | :func:`mode` 216 | :func:`colormode` 217 | :func:`getcanvas` 218 | :func:`getshapes` 219 | :func:`register_shape` | :func:`addshape` 220 | :func:`turtles` 221 | :func:`window_height` 222 | :func:`window_width` 223 224Input methods 225 | :func:`textinput` 226 | :func:`numinput` 227 228Methods specific to Screen 229 | :func:`bye` 230 | :func:`exitonclick` 231 | :func:`setup` 232 | :func:`title` 233 234 235Methods of RawTurtle/Turtle and corresponding functions 236======================================================= 237 238Most of the examples in this section refer to a Turtle instance called 239``turtle``. 240 241Turtle motion 242------------- 243 244.. function:: forward(distance) 245 fd(distance) 246 247 :param distance: a number (integer or float) 248 249 Move the turtle forward by the specified *distance*, in the direction the 250 turtle is headed. 251 252 .. doctest:: 253 :skipif: _tkinter is None 254 255 >>> turtle.position() 256 (0.00,0.00) 257 >>> turtle.forward(25) 258 >>> turtle.position() 259 (25.00,0.00) 260 >>> turtle.forward(-75) 261 >>> turtle.position() 262 (-50.00,0.00) 263 264 265.. function:: back(distance) 266 bk(distance) 267 backward(distance) 268 269 :param distance: a number 270 271 Move the turtle backward by *distance*, opposite to the direction the 272 turtle is headed. Do not change the turtle's heading. 273 274 .. doctest:: 275 :hide: 276 277 >>> turtle.goto(0, 0) 278 279 .. doctest:: 280 :skipif: _tkinter is None 281 282 >>> turtle.position() 283 (0.00,0.00) 284 >>> turtle.backward(30) 285 >>> turtle.position() 286 (-30.00,0.00) 287 288 289.. function:: right(angle) 290 rt(angle) 291 292 :param angle: a number (integer or float) 293 294 Turn turtle right 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 :skipif: _tkinter is None 300 :hide: 301 302 >>> turtle.setheading(22) 303 304 .. doctest:: 305 :skipif: _tkinter is None 306 307 >>> turtle.heading() 308 22.0 309 >>> turtle.right(45) 310 >>> turtle.heading() 311 337.0 312 313 314.. function:: left(angle) 315 lt(angle) 316 317 :param angle: a number (integer or float) 318 319 Turn turtle left by *angle* units. (Units are by default degrees, but 320 can be set via the :func:`degrees` and :func:`radians` functions.) Angle 321 orientation depends on the turtle mode, see :func:`mode`. 322 323 .. doctest:: 324 :skipif: _tkinter is None 325 :hide: 326 327 >>> turtle.setheading(22) 328 329 .. doctest:: 330 :skipif: _tkinter is None 331 332 >>> turtle.heading() 333 22.0 334 >>> turtle.left(45) 335 >>> turtle.heading() 336 67.0 337 338 339.. function:: goto(x, y=None) 340 setpos(x, y=None) 341 setposition(x, y=None) 342 343 :param x: a number or a pair/vector of numbers 344 :param y: a number or ``None`` 345 346 If *y* is ``None``, *x* must be a pair of coordinates or a :class:`Vec2D` 347 (e.g. as returned by :func:`pos`). 348 349 Move turtle to an absolute position. If the pen is down, draw line. Do 350 not change the turtle's orientation. 351 352 .. doctest:: 353 :skipif: _tkinter is None 354 :hide: 355 356 >>> turtle.goto(0, 0) 357 358 .. doctest:: 359 :skipif: _tkinter is None 360 361 >>> tp = turtle.pos() 362 >>> tp 363 (0.00,0.00) 364 >>> turtle.setpos(60,30) 365 >>> turtle.pos() 366 (60.00,30.00) 367 >>> turtle.setpos((20,80)) 368 >>> turtle.pos() 369 (20.00,80.00) 370 >>> turtle.setpos(tp) 371 >>> turtle.pos() 372 (0.00,0.00) 373 374 375.. function:: setx(x) 376 377 :param x: a number (integer or float) 378 379 Set the turtle's first coordinate to *x*, leave second coordinate 380 unchanged. 381 382 .. doctest:: 383 :skipif: _tkinter is None 384 :hide: 385 386 >>> turtle.goto(0, 240) 387 388 .. doctest:: 389 :skipif: _tkinter is None 390 391 >>> turtle.position() 392 (0.00,240.00) 393 >>> turtle.setx(10) 394 >>> turtle.position() 395 (10.00,240.00) 396 397 398.. function:: sety(y) 399 400 :param y: a number (integer or float) 401 402 Set the turtle's second coordinate to *y*, leave first coordinate unchanged. 403 404 .. doctest:: 405 :skipif: _tkinter is None 406 :hide: 407 408 >>> turtle.goto(0, 40) 409 410 .. doctest:: 411 :skipif: _tkinter is None 412 413 >>> turtle.position() 414 (0.00,40.00) 415 >>> turtle.sety(-10) 416 >>> turtle.position() 417 (0.00,-10.00) 418 419 420.. function:: setheading(to_angle) 421 seth(to_angle) 422 423 :param to_angle: a number (integer or float) 424 425 Set the orientation of the turtle to *to_angle*. Here are some common 426 directions in degrees: 427 428 =================== ==================== 429 standard mode logo mode 430 =================== ==================== 431 0 - east 0 - north 432 90 - north 90 - east 433 180 - west 180 - south 434 270 - south 270 - west 435 =================== ==================== 436 437 .. doctest:: 438 :skipif: _tkinter is None 439 440 >>> turtle.setheading(90) 441 >>> turtle.heading() 442 90.0 443 444 445.. function:: home() 446 447 Move turtle to the origin -- coordinates (0,0) -- and set its heading to 448 its start-orientation (which depends on the mode, see :func:`mode`). 449 450 .. doctest:: 451 :skipif: _tkinter is None 452 :hide: 453 454 >>> turtle.setheading(90) 455 >>> turtle.goto(0, -10) 456 457 .. doctest:: 458 :skipif: _tkinter is None 459 460 >>> turtle.heading() 461 90.0 462 >>> turtle.position() 463 (0.00,-10.00) 464 >>> turtle.home() 465 >>> turtle.position() 466 (0.00,0.00) 467 >>> turtle.heading() 468 0.0 469 470 471.. function:: circle(radius, extent=None, steps=None) 472 473 :param radius: a number 474 :param extent: a number (or ``None``) 475 :param steps: an integer (or ``None``) 476 477 Draw a circle with given *radius*. The center is *radius* units left of 478 the turtle; *extent* -- an angle -- determines which part of the circle 479 is drawn. If *extent* is not given, draw the entire circle. If *extent* 480 is not a full circle, one endpoint of the arc is the current pen 481 position. Draw the arc in counterclockwise direction if *radius* is 482 positive, otherwise in clockwise direction. Finally the direction of the 483 turtle is changed by the amount of *extent*. 484 485 As the circle is approximated by an inscribed regular polygon, *steps* 486 determines the number of steps to use. If not given, it will be 487 calculated automatically. May be used to draw regular polygons. 488 489 .. doctest:: 490 :skipif: _tkinter is None 491 492 >>> turtle.home() 493 >>> turtle.position() 494 (0.00,0.00) 495 >>> turtle.heading() 496 0.0 497 >>> turtle.circle(50) 498 >>> turtle.position() 499 (-0.00,0.00) 500 >>> turtle.heading() 501 0.0 502 >>> turtle.circle(120, 180) # draw a semicircle 503 >>> turtle.position() 504 (0.00,240.00) 505 >>> turtle.heading() 506 180.0 507 508 509.. function:: dot(size=None, *color) 510 511 :param size: an integer >= 1 (if given) 512 :param color: a colorstring or a numeric color tuple 513 514 Draw a circular dot with diameter *size*, using *color*. If *size* is 515 not given, the maximum of pensize+4 and 2*pensize is used. 516 517 518 .. doctest:: 519 :skipif: _tkinter is None 520 521 >>> turtle.home() 522 >>> turtle.dot() 523 >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50) 524 >>> turtle.position() 525 (100.00,-0.00) 526 >>> turtle.heading() 527 0.0 528 529 530.. function:: stamp() 531 532 Stamp a copy of the turtle shape onto the canvas at the current turtle 533 position. Return a stamp_id for that stamp, which can be used to delete 534 it by calling ``clearstamp(stamp_id)``. 535 536 .. doctest:: 537 :skipif: _tkinter is None 538 539 >>> turtle.color("blue") 540 >>> turtle.stamp() 541 11 542 >>> turtle.fd(50) 543 544 545.. function:: clearstamp(stampid) 546 547 :param stampid: an integer, must be return value of previous 548 :func:`stamp` call 549 550 Delete stamp with given *stampid*. 551 552 .. doctest:: 553 :skipif: _tkinter is None 554 555 >>> turtle.position() 556 (150.00,-0.00) 557 >>> turtle.color("blue") 558 >>> astamp = turtle.stamp() 559 >>> turtle.fd(50) 560 >>> turtle.position() 561 (200.00,-0.00) 562 >>> turtle.clearstamp(astamp) 563 >>> turtle.position() 564 (200.00,-0.00) 565 566 567.. function:: clearstamps(n=None) 568 569 :param n: an integer (or ``None``) 570 571 Delete all or first/last *n* of turtle's stamps. If *n* is ``None``, delete 572 all stamps, if *n* > 0 delete first *n* stamps, else if *n* < 0 delete 573 last *n* stamps. 574 575 .. doctest:: 576 577 >>> for i in range(8): 578 ... turtle.stamp(); turtle.fd(30) 579 13 580 14 581 15 582 16 583 17 584 18 585 19 586 20 587 >>> turtle.clearstamps(2) 588 >>> turtle.clearstamps(-2) 589 >>> turtle.clearstamps() 590 591 592.. function:: undo() 593 594 Undo (repeatedly) the last turtle action(s). Number of available 595 undo actions is determined by the size of the undobuffer. 596 597 .. doctest:: 598 :skipif: _tkinter is None 599 600 >>> for i in range(4): 601 ... turtle.fd(50); turtle.lt(80) 602 ... 603 >>> for i in range(8): 604 ... turtle.undo() 605 606 607.. function:: speed(speed=None) 608 609 :param speed: an integer in the range 0..10 or a speedstring (see below) 610 611 Set the turtle's speed to an integer value in the range 0..10. If no 612 argument is given, return current speed. 613 614 If input is a number greater than 10 or smaller than 0.5, speed is set 615 to 0. Speedstrings are mapped to speedvalues as follows: 616 617 * "fastest": 0 618 * "fast": 10 619 * "normal": 6 620 * "slow": 3 621 * "slowest": 1 622 623 Speeds from 1 to 10 enforce increasingly faster animation of line drawing 624 and turtle turning. 625 626 Attention: *speed* = 0 means that *no* animation takes 627 place. forward/back makes turtle jump and likewise left/right make the 628 turtle turn instantly. 629 630 .. doctest:: 631 :skipif: _tkinter is None 632 633 >>> turtle.speed() 634 3 635 >>> turtle.speed('normal') 636 >>> turtle.speed() 637 6 638 >>> turtle.speed(9) 639 >>> turtle.speed() 640 9 641 642 643Tell Turtle's state 644------------------- 645 646.. function:: position() 647 pos() 648 649 Return the turtle's current location (x,y) (as a :class:`Vec2D` vector). 650 651 .. doctest:: 652 :skipif: _tkinter is None 653 654 >>> turtle.pos() 655 (440.00,-0.00) 656 657 658.. function:: towards(x, y=None) 659 660 :param x: a number or a pair/vector of numbers or a turtle instance 661 :param y: a number if *x* is a number, else ``None`` 662 663 Return the angle between the line from turtle position to position specified 664 by (x,y), the vector or the other turtle. This depends on the turtle's start 665 orientation which depends on the mode - "standard"/"world" or "logo". 666 667 .. doctest:: 668 :skipif: _tkinter is None 669 670 >>> turtle.goto(10, 10) 671 >>> turtle.towards(0,0) 672 225.0 673 674 675.. function:: xcor() 676 677 Return the turtle's x coordinate. 678 679 .. doctest:: 680 :skipif: _tkinter is None 681 682 >>> turtle.home() 683 >>> turtle.left(50) 684 >>> turtle.forward(100) 685 >>> turtle.pos() 686 (64.28,76.60) 687 >>> print(round(turtle.xcor(), 5)) 688 64.27876 689 690 691.. function:: ycor() 692 693 Return the turtle's y coordinate. 694 695 .. doctest:: 696 :skipif: _tkinter is None 697 698 >>> turtle.home() 699 >>> turtle.left(60) 700 >>> turtle.forward(100) 701 >>> print(turtle.pos()) 702 (50.00,86.60) 703 >>> print(round(turtle.ycor(), 5)) 704 86.60254 705 706 707.. function:: heading() 708 709 Return the turtle's current heading (value depends on the turtle mode, see 710 :func:`mode`). 711 712 .. doctest:: 713 :skipif: _tkinter is None 714 715 >>> turtle.home() 716 >>> turtle.left(67) 717 >>> turtle.heading() 718 67.0 719 720 721.. function:: distance(x, y=None) 722 723 :param x: a number or a pair/vector of numbers or a turtle instance 724 :param y: a number if *x* is a number, else ``None`` 725 726 Return the distance from the turtle to (x,y), the given vector, or the given 727 other turtle, in turtle step units. 728 729 .. doctest:: 730 :skipif: _tkinter is None 731 732 >>> turtle.home() 733 >>> turtle.distance(30,40) 734 50.0 735 >>> turtle.distance((30,40)) 736 50.0 737 >>> joe = Turtle() 738 >>> joe.forward(77) 739 >>> turtle.distance(joe) 740 77.0 741 742 743Settings for measurement 744------------------------ 745 746.. function:: degrees(fullcircle=360.0) 747 748 :param fullcircle: a number 749 750 Set angle measurement units, i.e. set number of "degrees" for a full circle. 751 Default value is 360 degrees. 752 753 .. doctest:: 754 :skipif: _tkinter is None 755 756 >>> turtle.home() 757 >>> turtle.left(90) 758 >>> turtle.heading() 759 90.0 760 761 Change angle measurement unit to grad (also known as gon, 762 grade, or gradian and equals 1/100-th of the right angle.) 763 >>> turtle.degrees(400.0) 764 >>> turtle.heading() 765 100.0 766 >>> turtle.degrees(360) 767 >>> turtle.heading() 768 90.0 769 770 771.. function:: radians() 772 773 Set the angle measurement units to radians. Equivalent to 774 ``degrees(2*math.pi)``. 775 776 .. doctest:: 777 :skipif: _tkinter is None 778 779 >>> turtle.home() 780 >>> turtle.left(90) 781 >>> turtle.heading() 782 90.0 783 >>> turtle.radians() 784 >>> turtle.heading() 785 1.5707963267948966 786 787 .. doctest:: 788 :skipif: _tkinter is None 789 :hide: 790 791 >>> turtle.degrees(360) 792 793 794Pen control 795----------- 796 797Drawing state 798~~~~~~~~~~~~~ 799 800.. function:: pendown() 801 pd() 802 down() 803 804 Pull the pen down -- drawing when moving. 805 806 807.. function:: penup() 808 pu() 809 up() 810 811 Pull the pen up -- no drawing when moving. 812 813 814.. function:: pensize(width=None) 815 width(width=None) 816 817 :param width: a positive number 818 819 Set the line thickness to *width* or return it. If resizemode is set to 820 "auto" and turtleshape is a polygon, that polygon is drawn with the same line 821 thickness. If no argument is given, the current pensize is returned. 822 823 .. doctest:: 824 :skipif: _tkinter is None 825 826 >>> turtle.pensize() 827 1 828 >>> turtle.pensize(10) # from here on lines of width 10 are drawn 829 830 831.. function:: pen(pen=None, **pendict) 832 833 :param pen: a dictionary with some or all of the below listed keys 834 :param pendict: one or more keyword-arguments with the below listed keys as keywords 835 836 Return or set the pen's attributes in a "pen-dictionary" with the following 837 key/value pairs: 838 839 * "shown": True/False 840 * "pendown": True/False 841 * "pencolor": color-string or color-tuple 842 * "fillcolor": color-string or color-tuple 843 * "pensize": positive number 844 * "speed": number in range 0..10 845 * "resizemode": "auto" or "user" or "noresize" 846 * "stretchfactor": (positive number, positive number) 847 * "outline": positive number 848 * "tilt": number 849 850 This dictionary can be used as argument for a subsequent call to :func:`pen` 851 to restore the former pen-state. Moreover one or more of these attributes 852 can be provided as keyword-arguments. This can be used to set several pen 853 attributes in one statement. 854 855 .. doctest:: 856 :skipif: _tkinter is None 857 :options: +NORMALIZE_WHITESPACE 858 859 >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10) 860 >>> sorted(turtle.pen().items()) 861 [('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'), 862 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'), 863 ('shearfactor', 0.0), ('shown', True), ('speed', 9), 864 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)] 865 >>> penstate=turtle.pen() 866 >>> turtle.color("yellow", "") 867 >>> turtle.penup() 868 >>> sorted(turtle.pen().items())[:3] 869 [('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')] 870 >>> turtle.pen(penstate, fillcolor="green") 871 >>> sorted(turtle.pen().items())[:3] 872 [('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')] 873 874.. function:: isdown() 875 876 Return ``True`` if pen is down, ``False`` if it's up. 877 878 .. doctest:: 879 :skipif: _tkinter is None 880 881 >>> turtle.penup() 882 >>> turtle.isdown() 883 False 884 >>> turtle.pendown() 885 >>> turtle.isdown() 886 True 887 888 889Color control 890~~~~~~~~~~~~~ 891 892.. function:: pencolor(*args) 893 894 Return or set the pencolor. 895 896 Four input formats are allowed: 897 898 ``pencolor()`` 899 Return the current pencolor as color specification string or 900 as a tuple (see example). May be used as input to another 901 color/pencolor/fillcolor call. 902 903 ``pencolor(colorstring)`` 904 Set pencolor to *colorstring*, which is a Tk color specification string, 905 such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. 906 907 ``pencolor((r, g, b))`` 908 Set pencolor to the RGB color represented by the tuple of *r*, *g*, and 909 *b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where 910 colormode is either 1.0 or 255 (see :func:`colormode`). 911 912 ``pencolor(r, g, b)`` 913 Set pencolor to the RGB color represented by *r*, *g*, and *b*. Each of 914 *r*, *g*, and *b* must be in the range 0..colormode. 915 916 If turtleshape is a polygon, the outline of that polygon is drawn with the 917 newly set pencolor. 918 919 .. doctest:: 920 :skipif: _tkinter is None 921 922 >>> colormode() 923 1.0 924 >>> turtle.pencolor() 925 'red' 926 >>> turtle.pencolor("brown") 927 >>> turtle.pencolor() 928 'brown' 929 >>> tup = (0.2, 0.8, 0.55) 930 >>> turtle.pencolor(tup) 931 >>> turtle.pencolor() 932 (0.2, 0.8, 0.5490196078431373) 933 >>> colormode(255) 934 >>> turtle.pencolor() 935 (51.0, 204.0, 140.0) 936 >>> turtle.pencolor('#32c18f') 937 >>> turtle.pencolor() 938 (50.0, 193.0, 143.0) 939 940 941.. function:: fillcolor(*args) 942 943 Return or set the fillcolor. 944 945 Four input formats are allowed: 946 947 ``fillcolor()`` 948 Return the current fillcolor as color specification string, possibly 949 in tuple format (see example). May be used as input to another 950 color/pencolor/fillcolor call. 951 952 ``fillcolor(colorstring)`` 953 Set fillcolor to *colorstring*, which is a Tk color specification string, 954 such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. 955 956 ``fillcolor((r, g, b))`` 957 Set fillcolor to the RGB color represented by the tuple of *r*, *g*, and 958 *b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where 959 colormode is either 1.0 or 255 (see :func:`colormode`). 960 961 ``fillcolor(r, g, b)`` 962 Set fillcolor to the RGB color represented by *r*, *g*, and *b*. Each of 963 *r*, *g*, and *b* must be in the range 0..colormode. 964 965 If turtleshape is a polygon, the interior of that polygon is drawn 966 with the newly set fillcolor. 967 968 .. doctest:: 969 :skipif: _tkinter is None 970 971 >>> turtle.fillcolor("violet") 972 >>> turtle.fillcolor() 973 'violet' 974 >>> turtle.pencolor() 975 (50.0, 193.0, 143.0) 976 >>> turtle.fillcolor((50, 193, 143)) # Integers, not floats 977 >>> turtle.fillcolor() 978 (50.0, 193.0, 143.0) 979 >>> turtle.fillcolor('#ffffff') 980 >>> turtle.fillcolor() 981 (255.0, 255.0, 255.0) 982 983 984.. function:: color(*args) 985 986 Return or set pencolor and fillcolor. 987 988 Several input formats are allowed. They use 0 to 3 arguments as 989 follows: 990 991 ``color()`` 992 Return the current pencolor and the current fillcolor as a pair of color 993 specification strings or tuples as returned by :func:`pencolor` and 994 :func:`fillcolor`. 995 996 ``color(colorstring)``, ``color((r,g,b))``, ``color(r,g,b)`` 997 Inputs as in :func:`pencolor`, set both, fillcolor and pencolor, to the 998 given value. 999 1000 ``color(colorstring1, colorstring2)``, ``color((r1,g1,b1), (r2,g2,b2))`` 1001 Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)`` 1002 and analogously if the other input format is used. 1003 1004 If turtleshape is a polygon, outline and interior of that polygon is drawn 1005 with the newly set colors. 1006 1007 .. doctest:: 1008 :skipif: _tkinter is None 1009 1010 >>> turtle.color("red", "green") 1011 >>> turtle.color() 1012 ('red', 'green') 1013 >>> color("#285078", "#a0c8f0") 1014 >>> color() 1015 ((40.0, 80.0, 120.0), (160.0, 200.0, 240.0)) 1016 1017 1018See also: Screen method :func:`colormode`. 1019 1020 1021Filling 1022~~~~~~~ 1023 1024.. doctest:: 1025 :skipif: _tkinter is None 1026 :hide: 1027 1028 >>> turtle.home() 1029 1030.. function:: filling() 1031 1032 Return fillstate (``True`` if filling, ``False`` else). 1033 1034 .. doctest:: 1035 :skipif: _tkinter is None 1036 1037 >>> turtle.begin_fill() 1038 >>> if turtle.filling(): 1039 ... turtle.pensize(5) 1040 ... else: 1041 ... turtle.pensize(3) 1042 1043 1044 1045.. function:: begin_fill() 1046 1047 To be called just before drawing a shape to be filled. 1048 1049 1050.. function:: end_fill() 1051 1052 Fill the shape drawn after the last call to :func:`begin_fill`. 1053 1054 Whether or not overlap regions for self-intersecting polygons 1055 or multiple shapes are filled depends on the operating system graphics, 1056 type of overlap, and number of overlaps. For example, the Turtle star 1057 above may be either all yellow or have some white regions. 1058 1059 .. doctest:: 1060 :skipif: _tkinter is None 1061 1062 >>> turtle.color("black", "red") 1063 >>> turtle.begin_fill() 1064 >>> turtle.circle(80) 1065 >>> turtle.end_fill() 1066 1067 1068More drawing control 1069~~~~~~~~~~~~~~~~~~~~ 1070 1071.. function:: reset() 1072 :noindex: 1073 1074 Delete the turtle's drawings from the screen, re-center the turtle and set 1075 variables to the default values. 1076 1077 .. doctest:: 1078 :skipif: _tkinter is None 1079 1080 >>> turtle.goto(0,-22) 1081 >>> turtle.left(100) 1082 >>> turtle.position() 1083 (0.00,-22.00) 1084 >>> turtle.heading() 1085 100.0 1086 >>> turtle.reset() 1087 >>> turtle.position() 1088 (0.00,0.00) 1089 >>> turtle.heading() 1090 0.0 1091 1092 1093.. function:: clear() 1094 :noindex: 1095 1096 Delete the turtle's drawings from the screen. Do not move turtle. State and 1097 position of the turtle as well as drawings of other turtles are not affected. 1098 1099 1100.. function:: write(arg, move=False, align="left", font=("Arial", 8, "normal")) 1101 1102 :param arg: object to be written to the TurtleScreen 1103 :param move: True/False 1104 :param align: one of the strings "left", "center" or right" 1105 :param font: a triple (fontname, fontsize, fonttype) 1106 1107 Write text - the string representation of *arg* - at the current turtle 1108 position according to *align* ("left", "center" or "right") and with the given 1109 font. If *move* is true, the pen is moved to the bottom-right corner of the 1110 text. By default, *move* is ``False``. 1111 1112 >>> turtle.write("Home = ", True, align="center") 1113 >>> turtle.write((0,0), True) 1114 1115 1116Turtle state 1117------------ 1118 1119Visibility 1120~~~~~~~~~~ 1121 1122.. function:: hideturtle() 1123 ht() 1124 1125 Make the turtle invisible. It's a good idea to do this while you're in the 1126 middle of doing some complex drawing, because hiding the turtle speeds up the 1127 drawing observably. 1128 1129 .. doctest:: 1130 :skipif: _tkinter is None 1131 1132 >>> turtle.hideturtle() 1133 1134 1135.. function:: showturtle() 1136 st() 1137 1138 Make the turtle visible. 1139 1140 .. doctest:: 1141 :skipif: _tkinter is None 1142 1143 >>> turtle.showturtle() 1144 1145 1146.. function:: isvisible() 1147 1148 Return ``True`` if the Turtle is shown, ``False`` if it's hidden. 1149 1150 >>> turtle.hideturtle() 1151 >>> turtle.isvisible() 1152 False 1153 >>> turtle.showturtle() 1154 >>> turtle.isvisible() 1155 True 1156 1157 1158Appearance 1159~~~~~~~~~~ 1160 1161.. function:: shape(name=None) 1162 1163 :param name: a string which is a valid shapename 1164 1165 Set turtle shape to shape with given *name* or, if name is not given, return 1166 name of current shape. Shape with *name* must exist in the TurtleScreen's 1167 shape dictionary. Initially there are the following polygon shapes: "arrow", 1168 "turtle", "circle", "square", "triangle", "classic". To learn about how to 1169 deal with shapes see Screen method :func:`register_shape`. 1170 1171 .. doctest:: 1172 :skipif: _tkinter is None 1173 1174 >>> turtle.shape() 1175 'classic' 1176 >>> turtle.shape("turtle") 1177 >>> turtle.shape() 1178 'turtle' 1179 1180 1181.. function:: resizemode(rmode=None) 1182 1183 :param rmode: one of the strings "auto", "user", "noresize" 1184 1185 Set resizemode to one of the values: "auto", "user", "noresize". If *rmode* 1186 is not given, return current resizemode. Different resizemodes have the 1187 following effects: 1188 1189 - "auto": adapts the appearance of the turtle corresponding to the value of pensize. 1190 - "user": adapts the appearance of the turtle according to the values of 1191 stretchfactor and outlinewidth (outline), which are set by 1192 :func:`shapesize`. 1193 - "noresize": no adaption of the turtle's appearance takes place. 1194 1195 ``resizemode("user")`` is called by :func:`shapesize` when used with arguments. 1196 1197 .. doctest:: 1198 :skipif: _tkinter is None 1199 1200 >>> turtle.resizemode() 1201 'noresize' 1202 >>> turtle.resizemode("auto") 1203 >>> turtle.resizemode() 1204 'auto' 1205 1206 1207.. function:: shapesize(stretch_wid=None, stretch_len=None, outline=None) 1208 turtlesize(stretch_wid=None, stretch_len=None, outline=None) 1209 1210 :param stretch_wid: positive number 1211 :param stretch_len: positive number 1212 :param outline: positive number 1213 1214 Return or set the pen's attributes x/y-stretchfactors and/or outline. Set 1215 resizemode to "user". If and only if resizemode is set to "user", the turtle 1216 will be displayed stretched according to its stretchfactors: *stretch_wid* is 1217 stretchfactor perpendicular to its orientation, *stretch_len* is 1218 stretchfactor in direction of its orientation, *outline* determines the width 1219 of the shapes's outline. 1220 1221 .. doctest:: 1222 :skipif: _tkinter is None 1223 1224 >>> turtle.shapesize() 1225 (1.0, 1.0, 1) 1226 >>> turtle.resizemode("user") 1227 >>> turtle.shapesize(5, 5, 12) 1228 >>> turtle.shapesize() 1229 (5, 5, 12) 1230 >>> turtle.shapesize(outline=8) 1231 >>> turtle.shapesize() 1232 (5, 5, 8) 1233 1234 1235.. function:: shearfactor(shear=None) 1236 1237 :param shear: number (optional) 1238 1239 Set or return the current shearfactor. Shear the turtleshape according to 1240 the given shearfactor shear, which is the tangent of the shear angle. 1241 Do *not* change the turtle's heading (direction of movement). 1242 If shear is not given: return the current shearfactor, i. e. the 1243 tangent of the shear angle, by which lines parallel to the 1244 heading of the turtle are sheared. 1245 1246 .. doctest:: 1247 :skipif: _tkinter is None 1248 1249 >>> turtle.shape("circle") 1250 >>> turtle.shapesize(5,2) 1251 >>> turtle.shearfactor(0.5) 1252 >>> turtle.shearfactor() 1253 0.5 1254 1255 1256.. function:: tilt(angle) 1257 1258 :param angle: a number 1259 1260 Rotate the turtleshape by *angle* from its current tilt-angle, but do *not* 1261 change the turtle's heading (direction of movement). 1262 1263 .. doctest:: 1264 :skipif: _tkinter is None 1265 1266 >>> turtle.reset() 1267 >>> turtle.shape("circle") 1268 >>> turtle.shapesize(5,2) 1269 >>> turtle.tilt(30) 1270 >>> turtle.fd(50) 1271 >>> turtle.tilt(30) 1272 >>> turtle.fd(50) 1273 1274 1275.. function:: settiltangle(angle) 1276 1277 :param angle: a number 1278 1279 Rotate the turtleshape to point in the direction specified by *angle*, 1280 regardless of its current tilt-angle. *Do not* change the turtle's heading 1281 (direction of movement). 1282 1283 .. doctest:: 1284 :skipif: _tkinter is None 1285 1286 >>> turtle.reset() 1287 >>> turtle.shape("circle") 1288 >>> turtle.shapesize(5,2) 1289 >>> turtle.settiltangle(45) 1290 >>> turtle.fd(50) 1291 >>> turtle.settiltangle(-45) 1292 >>> turtle.fd(50) 1293 1294 .. deprecated:: 3.1 1295 1296 1297.. function:: tiltangle(angle=None) 1298 1299 :param angle: a number (optional) 1300 1301 Set or return the current tilt-angle. If angle is given, rotate the 1302 turtleshape to point in the direction specified by angle, 1303 regardless of its current tilt-angle. Do *not* change the turtle's 1304 heading (direction of movement). 1305 If angle is not given: return the current tilt-angle, i. e. the angle 1306 between the orientation of the turtleshape and the heading of the 1307 turtle (its direction of movement). 1308 1309 .. doctest:: 1310 :skipif: _tkinter is None 1311 1312 >>> turtle.reset() 1313 >>> turtle.shape("circle") 1314 >>> turtle.shapesize(5,2) 1315 >>> turtle.tilt(45) 1316 >>> turtle.tiltangle() 1317 45.0 1318 1319 1320.. function:: shapetransform(t11=None, t12=None, t21=None, t22=None) 1321 1322 :param t11: a number (optional) 1323 :param t12: a number (optional) 1324 :param t21: a number (optional) 1325 :param t12: a number (optional) 1326 1327 Set or return the current transformation matrix of the turtle shape. 1328 1329 If none of the matrix elements are given, return the transformation 1330 matrix as a tuple of 4 elements. 1331 Otherwise set the given elements and transform the turtleshape 1332 according to the matrix consisting of first row t11, t12 and 1333 second row t21, t22. The determinant t11 * t22 - t12 * t21 must not be 1334 zero, otherwise an error is raised. 1335 Modify stretchfactor, shearfactor and tiltangle according to the 1336 given matrix. 1337 1338 .. doctest:: 1339 :skipif: _tkinter is None 1340 1341 >>> turtle = Turtle() 1342 >>> turtle.shape("square") 1343 >>> turtle.shapesize(4,2) 1344 >>> turtle.shearfactor(-0.5) 1345 >>> turtle.shapetransform() 1346 (4.0, -1.0, -0.0, 2.0) 1347 1348 1349.. function:: get_shapepoly() 1350 1351 Return the current shape polygon as tuple of coordinate pairs. This 1352 can be used to define a new shape or components of a compound shape. 1353 1354 .. doctest:: 1355 :skipif: _tkinter is None 1356 1357 >>> turtle.shape("square") 1358 >>> turtle.shapetransform(4, -1, 0, 2) 1359 >>> turtle.get_shapepoly() 1360 ((50, -20), (30, 20), (-50, 20), (-30, -20)) 1361 1362 1363Using events 1364------------ 1365 1366.. function:: onclick(fun, btn=1, add=None) 1367 :noindex: 1368 1369 :param fun: a function with two arguments which will be called with the 1370 coordinates of the clicked point on the canvas 1371 :param btn: number of the mouse-button, defaults to 1 (left mouse button) 1372 :param add: ``True`` or ``False`` -- if ``True``, a new binding will be 1373 added, otherwise it will replace a former binding 1374 1375 Bind *fun* to mouse-click events on this turtle. If *fun* is ``None``, 1376 existing bindings are removed. Example for the anonymous turtle, i.e. the 1377 procedural way: 1378 1379 .. doctest:: 1380 :skipif: _tkinter is None 1381 1382 >>> def turn(x, y): 1383 ... left(180) 1384 ... 1385 >>> onclick(turn) # Now clicking into the turtle will turn it. 1386 >>> onclick(None) # event-binding will be removed 1387 1388 1389.. function:: onrelease(fun, btn=1, add=None) 1390 1391 :param fun: a function with two arguments which will be called with the 1392 coordinates of the clicked point on the canvas 1393 :param btn: number of the mouse-button, defaults to 1 (left mouse button) 1394 :param add: ``True`` or ``False`` -- if ``True``, a new binding will be 1395 added, otherwise it will replace a former binding 1396 1397 Bind *fun* to mouse-button-release events on this turtle. If *fun* is 1398 ``None``, existing bindings are removed. 1399 1400 .. doctest:: 1401 :skipif: _tkinter is None 1402 1403 >>> class MyTurtle(Turtle): 1404 ... def glow(self,x,y): 1405 ... self.fillcolor("red") 1406 ... def unglow(self,x,y): 1407 ... self.fillcolor("") 1408 ... 1409 >>> turtle = MyTurtle() 1410 >>> turtle.onclick(turtle.glow) # clicking on turtle turns fillcolor red, 1411 >>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent. 1412 1413 1414.. function:: ondrag(fun, btn=1, add=None) 1415 1416 :param fun: a function with two arguments which will be called with the 1417 coordinates of the clicked point on the canvas 1418 :param btn: number of the mouse-button, defaults to 1 (left mouse button) 1419 :param add: ``True`` or ``False`` -- if ``True``, a new binding will be 1420 added, otherwise it will replace a former binding 1421 1422 Bind *fun* to mouse-move events on this turtle. If *fun* is ``None``, 1423 existing bindings are removed. 1424 1425 Remark: Every sequence of mouse-move-events on a turtle is preceded by a 1426 mouse-click event on that turtle. 1427 1428 .. doctest:: 1429 :skipif: _tkinter is None 1430 1431 >>> turtle.ondrag(turtle.goto) 1432 1433 Subsequently, clicking and dragging the Turtle will move it across 1434 the screen thereby producing handdrawings (if pen is down). 1435 1436 1437Special Turtle methods 1438---------------------- 1439 1440.. function:: begin_poly() 1441 1442 Start recording the vertices of a polygon. Current turtle position is first 1443 vertex of polygon. 1444 1445 1446.. function:: end_poly() 1447 1448 Stop recording the vertices of a polygon. Current turtle position is last 1449 vertex of polygon. This will be connected with the first vertex. 1450 1451 1452.. function:: get_poly() 1453 1454 Return the last recorded polygon. 1455 1456 .. doctest:: 1457 :skipif: _tkinter is None 1458 1459 >>> turtle.home() 1460 >>> turtle.begin_poly() 1461 >>> turtle.fd(100) 1462 >>> turtle.left(20) 1463 >>> turtle.fd(30) 1464 >>> turtle.left(60) 1465 >>> turtle.fd(50) 1466 >>> turtle.end_poly() 1467 >>> p = turtle.get_poly() 1468 >>> register_shape("myFavouriteShape", p) 1469 1470 1471.. function:: clone() 1472 1473 Create and return a clone of the turtle with same position, heading and 1474 turtle properties. 1475 1476 .. doctest:: 1477 :skipif: _tkinter is None 1478 1479 >>> mick = Turtle() 1480 >>> joe = mick.clone() 1481 1482 1483.. function:: getturtle() 1484 getpen() 1485 1486 Return the Turtle object itself. Only reasonable use: as a function to 1487 return the "anonymous turtle": 1488 1489 .. doctest:: 1490 :skipif: _tkinter is None 1491 1492 >>> pet = getturtle() 1493 >>> pet.fd(50) 1494 >>> pet 1495 <turtle.Turtle object at 0x...> 1496 1497 1498.. function:: getscreen() 1499 1500 Return the :class:`TurtleScreen` object the turtle is drawing on. 1501 TurtleScreen methods can then be called for that object. 1502 1503 .. doctest:: 1504 :skipif: _tkinter is None 1505 1506 >>> ts = turtle.getscreen() 1507 >>> ts 1508 <turtle._Screen object at 0x...> 1509 >>> ts.bgcolor("pink") 1510 1511 1512.. function:: setundobuffer(size) 1513 1514 :param size: an integer or ``None`` 1515 1516 Set or disable undobuffer. If *size* is an integer, an empty undobuffer of 1517 given size is installed. *size* gives the maximum number of turtle actions 1518 that can be undone by the :func:`undo` method/function. If *size* is 1519 ``None``, the undobuffer is disabled. 1520 1521 .. doctest:: 1522 :skipif: _tkinter is None 1523 1524 >>> turtle.setundobuffer(42) 1525 1526 1527.. function:: undobufferentries() 1528 1529 Return number of entries in the undobuffer. 1530 1531 .. doctest:: 1532 :skipif: _tkinter is None 1533 1534 >>> while undobufferentries(): 1535 ... undo() 1536 1537 1538 1539.. _compoundshapes: 1540 1541Compound shapes 1542--------------- 1543 1544To use compound turtle shapes, which consist of several polygons of different 1545color, you must use the helper class :class:`Shape` explicitly as described 1546below: 1547 15481. Create an empty Shape object of type "compound". 15492. Add as many components to this object as desired, using the 1550 :meth:`addcomponent` method. 1551 1552 For example: 1553 1554 .. doctest:: 1555 :skipif: _tkinter is None 1556 1557 >>> s = Shape("compound") 1558 >>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5)) 1559 >>> s.addcomponent(poly1, "red", "blue") 1560 >>> poly2 = ((0,0),(10,-5),(-10,-5)) 1561 >>> s.addcomponent(poly2, "blue", "red") 1562 15633. Now add the Shape to the Screen's shapelist and use it: 1564 1565 .. doctest:: 1566 :skipif: _tkinter is None 1567 1568 >>> register_shape("myshape", s) 1569 >>> shape("myshape") 1570 1571 1572.. note:: 1573 1574 The :class:`Shape` class is used internally by the :func:`register_shape` 1575 method in different ways. The application programmer has to deal with the 1576 Shape class *only* when using compound shapes like shown above! 1577 1578 1579Methods of TurtleScreen/Screen and corresponding functions 1580========================================================== 1581 1582Most of the examples in this section refer to a TurtleScreen instance called 1583``screen``. 1584 1585.. doctest:: 1586 :skipif: _tkinter is None 1587 :hide: 1588 1589 >>> screen = Screen() 1590 1591Window control 1592-------------- 1593 1594.. function:: bgcolor(*args) 1595 1596 :param args: a color string or three numbers in the range 0..colormode or a 1597 3-tuple of such numbers 1598 1599 1600 Set or return background color of the TurtleScreen. 1601 1602 .. doctest:: 1603 :skipif: _tkinter is None 1604 1605 >>> screen.bgcolor("orange") 1606 >>> screen.bgcolor() 1607 'orange' 1608 >>> screen.bgcolor("#800080") 1609 >>> screen.bgcolor() 1610 (128.0, 0.0, 128.0) 1611 1612 1613.. function:: bgpic(picname=None) 1614 1615 :param picname: a string, name of a gif-file or ``"nopic"``, or ``None`` 1616 1617 Set background image or return name of current backgroundimage. If *picname* 1618 is a filename, set the corresponding image as background. If *picname* is 1619 ``"nopic"``, delete background image, if present. If *picname* is ``None``, 1620 return the filename of the current backgroundimage. :: 1621 1622 >>> screen.bgpic() 1623 'nopic' 1624 >>> screen.bgpic("landscape.gif") 1625 >>> screen.bgpic() 1626 "landscape.gif" 1627 1628 1629.. function:: clear() 1630 clearscreen() 1631 1632 Delete all drawings and all turtles from the TurtleScreen. Reset the now 1633 empty TurtleScreen to its initial state: white background, no background 1634 image, no event bindings and tracing on. 1635 1636 .. note:: 1637 This TurtleScreen method is available as a global function only under the 1638 name ``clearscreen``. The global function ``clear`` is a different one 1639 derived from the Turtle method ``clear``. 1640 1641 1642.. function:: reset() 1643 resetscreen() 1644 1645 Reset all Turtles on the Screen to their initial state. 1646 1647 .. note:: 1648 This TurtleScreen method is available as a global function only under the 1649 name ``resetscreen``. The global function ``reset`` is another one 1650 derived from the Turtle method ``reset``. 1651 1652 1653.. function:: screensize(canvwidth=None, canvheight=None, bg=None) 1654 1655 :param canvwidth: positive integer, new width of canvas in pixels 1656 :param canvheight: positive integer, new height of canvas in pixels 1657 :param bg: colorstring or color-tuple, new background color 1658 1659 If no arguments are given, return current (canvaswidth, canvasheight). Else 1660 resize the canvas the turtles are drawing on. Do not alter the drawing 1661 window. To observe hidden parts of the canvas, use the scrollbars. With this 1662 method, one can make visible those parts of a drawing which were outside the 1663 canvas before. 1664 1665 >>> screen.screensize() 1666 (400, 300) 1667 >>> screen.screensize(2000,1500) 1668 >>> screen.screensize() 1669 (2000, 1500) 1670 1671 e.g. to search for an erroneously escaped turtle ;-) 1672 1673 1674.. function:: setworldcoordinates(llx, lly, urx, ury) 1675 1676 :param llx: a number, x-coordinate of lower left corner of canvas 1677 :param lly: a number, y-coordinate of lower left corner of canvas 1678 :param urx: a number, x-coordinate of upper right corner of canvas 1679 :param ury: a number, y-coordinate of upper right corner of canvas 1680 1681 Set up user-defined coordinate system and switch to mode "world" if 1682 necessary. This performs a ``screen.reset()``. If mode "world" is already 1683 active, all drawings are redrawn according to the new coordinates. 1684 1685 **ATTENTION**: in user-defined coordinate systems angles may appear 1686 distorted. 1687 1688 .. doctest:: 1689 :skipif: _tkinter is None 1690 1691 >>> screen.reset() 1692 >>> screen.setworldcoordinates(-50,-7.5,50,7.5) 1693 >>> for _ in range(72): 1694 ... left(10) 1695 ... 1696 >>> for _ in range(8): 1697 ... left(45); fd(2) # a regular octagon 1698 1699 .. doctest:: 1700 :skipif: _tkinter is None 1701 :hide: 1702 1703 >>> screen.reset() 1704 >>> for t in turtles(): 1705 ... t.reset() 1706 1707 1708Animation control 1709----------------- 1710 1711.. function:: delay(delay=None) 1712 1713 :param delay: positive integer 1714 1715 Set or return the drawing *delay* in milliseconds. (This is approximately 1716 the time interval between two consecutive canvas updates.) The longer the 1717 drawing delay, the slower the animation. 1718 1719 Optional argument: 1720 1721 .. doctest:: 1722 :skipif: _tkinter is None 1723 1724 >>> screen.delay() 1725 10 1726 >>> screen.delay(5) 1727 >>> screen.delay() 1728 5 1729 1730 1731.. function:: tracer(n=None, delay=None) 1732 1733 :param n: nonnegative integer 1734 :param delay: nonnegative integer 1735 1736 Turn turtle animation on/off and set delay for update drawings. If 1737 *n* is given, only each n-th regular screen update is really 1738 performed. (Can be used to accelerate the drawing of complex 1739 graphics.) When called without arguments, returns the currently 1740 stored value of n. Second argument sets delay value (see 1741 :func:`delay`). 1742 1743 .. doctest:: 1744 :skipif: _tkinter is None 1745 1746 >>> screen.tracer(8, 25) 1747 >>> dist = 2 1748 >>> for i in range(200): 1749 ... fd(dist) 1750 ... rt(90) 1751 ... dist += 2 1752 1753 1754.. function:: update() 1755 1756 Perform a TurtleScreen update. To be used when tracer is turned off. 1757 1758See also the RawTurtle/Turtle method :func:`speed`. 1759 1760 1761Using screen events 1762------------------- 1763 1764.. function:: listen(xdummy=None, ydummy=None) 1765 1766 Set focus on TurtleScreen (in order to collect key-events). Dummy arguments 1767 are provided in order to be able to pass :func:`listen` to the onclick method. 1768 1769 1770.. function:: onkey(fun, key) 1771 onkeyrelease(fun, key) 1772 1773 :param fun: a function with no arguments or ``None`` 1774 :param key: a string: key (e.g. "a") or key-symbol (e.g. "space") 1775 1776 Bind *fun* to key-release event of key. If *fun* is ``None``, event bindings 1777 are removed. Remark: in order to be able to register key-events, TurtleScreen 1778 must have the focus. (See method :func:`listen`.) 1779 1780 .. doctest:: 1781 :skipif: _tkinter is None 1782 1783 >>> def f(): 1784 ... fd(50) 1785 ... lt(60) 1786 ... 1787 >>> screen.onkey(f, "Up") 1788 >>> screen.listen() 1789 1790 1791.. function:: onkeypress(fun, key=None) 1792 1793 :param fun: a function with no arguments or ``None`` 1794 :param key: a string: key (e.g. "a") or key-symbol (e.g. "space") 1795 1796 Bind *fun* to key-press event of key if key is given, 1797 or to any key-press-event if no key is given. 1798 Remark: in order to be able to register key-events, TurtleScreen 1799 must have focus. (See method :func:`listen`.) 1800 1801 .. doctest:: 1802 :skipif: _tkinter is None 1803 1804 >>> def f(): 1805 ... fd(50) 1806 ... 1807 >>> screen.onkey(f, "Up") 1808 >>> screen.listen() 1809 1810 1811.. function:: onclick(fun, btn=1, add=None) 1812 onscreenclick(fun, btn=1, add=None) 1813 1814 :param fun: a function with two arguments which will be called with the 1815 coordinates of the clicked point on the canvas 1816 :param btn: number of the mouse-button, defaults to 1 (left mouse button) 1817 :param add: ``True`` or ``False`` -- if ``True``, a new binding will be 1818 added, otherwise it will replace a former binding 1819 1820 Bind *fun* to mouse-click events on this screen. If *fun* is ``None``, 1821 existing bindings are removed. 1822 1823 Example for a TurtleScreen instance named ``screen`` and a Turtle instance 1824 named ``turtle``: 1825 1826 .. doctest:: 1827 :skipif: _tkinter is None 1828 1829 >>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will 1830 >>> # make the turtle move to the clicked point. 1831 >>> screen.onclick(None) # remove event binding again 1832 1833 .. note:: 1834 This TurtleScreen method is available as a global function only under the 1835 name ``onscreenclick``. The global function ``onclick`` is another one 1836 derived from the Turtle method ``onclick``. 1837 1838 1839.. function:: ontimer(fun, t=0) 1840 1841 :param fun: a function with no arguments 1842 :param t: a number >= 0 1843 1844 Install a timer that calls *fun* after *t* milliseconds. 1845 1846 .. doctest:: 1847 :skipif: _tkinter is None 1848 1849 >>> running = True 1850 >>> def f(): 1851 ... if running: 1852 ... fd(50) 1853 ... lt(60) 1854 ... screen.ontimer(f, 250) 1855 >>> f() ### makes the turtle march around 1856 >>> running = False 1857 1858 1859.. function:: mainloop() 1860 done() 1861 1862 Starts event loop - calling Tkinter's mainloop function. 1863 Must be the last statement in a turtle graphics program. 1864 Must *not* be used if a script is run from within IDLE in -n mode 1865 (No subprocess) - for interactive use of turtle graphics. :: 1866 1867 >>> screen.mainloop() 1868 1869 1870Input methods 1871------------- 1872 1873.. function:: textinput(title, prompt) 1874 1875 :param title: string 1876 :param prompt: string 1877 1878 Pop up a dialog window for input of a string. Parameter title is 1879 the title of the dialog window, prompt is a text mostly describing 1880 what information to input. 1881 Return the string input. If the dialog is canceled, return ``None``. :: 1882 1883 >>> screen.textinput("NIM", "Name of first player:") 1884 1885 1886.. function:: numinput(title, prompt, default=None, minval=None, maxval=None) 1887 1888 :param title: string 1889 :param prompt: string 1890 :param default: number (optional) 1891 :param minval: number (optional) 1892 :param maxval: number (optional) 1893 1894 Pop up a dialog window for input of a number. title is the title of the 1895 dialog window, prompt is a text mostly describing what numerical information 1896 to input. default: default value, minval: minimum value for input, 1897 maxval: maximum value for input 1898 The number input must be in the range minval .. maxval if these are 1899 given. If not, a hint is issued and the dialog remains open for 1900 correction. 1901 Return the number input. If the dialog is canceled, return ``None``. :: 1902 1903 >>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000) 1904 1905 1906Settings and special methods 1907---------------------------- 1908 1909.. function:: mode(mode=None) 1910 1911 :param mode: one of the strings "standard", "logo" or "world" 1912 1913 Set turtle mode ("standard", "logo" or "world") and perform reset. If mode 1914 is not given, current mode is returned. 1915 1916 Mode "standard" is compatible with old :mod:`turtle`. Mode "logo" is 1917 compatible with most Logo turtle graphics. Mode "world" uses user-defined 1918 "world coordinates". **Attention**: in this mode angles appear distorted if 1919 ``x/y`` unit-ratio doesn't equal 1. 1920 1921 ============ ========================= =================== 1922 Mode Initial turtle heading positive angles 1923 ============ ========================= =================== 1924 "standard" to the right (east) counterclockwise 1925 "logo" upward (north) clockwise 1926 ============ ========================= =================== 1927 1928 .. doctest:: 1929 :skipif: _tkinter is None 1930 1931 >>> mode("logo") # resets turtle heading to north 1932 >>> mode() 1933 'logo' 1934 1935 1936.. function:: colormode(cmode=None) 1937 1938 :param cmode: one of the values 1.0 or 255 1939 1940 Return the colormode or set it to 1.0 or 255. Subsequently *r*, *g*, *b* 1941 values of color triples have to be in the range 0..\ *cmode*. 1942 1943 .. doctest:: 1944 :skipif: _tkinter is None 1945 1946 >>> screen.colormode(1) 1947 >>> turtle.pencolor(240, 160, 80) 1948 Traceback (most recent call last): 1949 ... 1950 TurtleGraphicsError: bad color sequence: (240, 160, 80) 1951 >>> screen.colormode() 1952 1.0 1953 >>> screen.colormode(255) 1954 >>> screen.colormode() 1955 255 1956 >>> turtle.pencolor(240,160,80) 1957 1958 1959.. function:: getcanvas() 1960 1961 Return the Canvas of this TurtleScreen. Useful for insiders who know what to 1962 do with a Tkinter Canvas. 1963 1964 .. doctest:: 1965 :skipif: _tkinter is None 1966 1967 >>> cv = screen.getcanvas() 1968 >>> cv 1969 <turtle.ScrolledCanvas object ...> 1970 1971 1972.. function:: getshapes() 1973 1974 Return a list of names of all currently available turtle shapes. 1975 1976 .. doctest:: 1977 :skipif: _tkinter is None 1978 1979 >>> screen.getshapes() 1980 ['arrow', 'blank', 'circle', ..., 'turtle'] 1981 1982 1983.. function:: register_shape(name, shape=None) 1984 addshape(name, shape=None) 1985 1986 There are three different ways to call this function: 1987 1988 (1) *name* is the name of a gif-file and *shape* is ``None``: Install the 1989 corresponding image shape. :: 1990 1991 >>> screen.register_shape("turtle.gif") 1992 1993 .. note:: 1994 Image shapes *do not* rotate when turning the turtle, so they do not 1995 display the heading of the turtle! 1996 1997 (2) *name* is an arbitrary string and *shape* is a tuple of pairs of 1998 coordinates: Install the corresponding polygon shape. 1999 2000 .. doctest:: 2001 :skipif: _tkinter is None 2002 2003 >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3))) 2004 2005 (3) *name* is an arbitrary string and shape is a (compound) :class:`Shape` 2006 object: Install the corresponding compound shape. 2007 2008 Add a turtle shape to TurtleScreen's shapelist. Only thusly registered 2009 shapes can be used by issuing the command ``shape(shapename)``. 2010 2011 2012.. function:: turtles() 2013 2014 Return the list of turtles on the screen. 2015 2016 .. doctest:: 2017 :skipif: _tkinter is None 2018 2019 >>> for turtle in screen.turtles(): 2020 ... turtle.color("red") 2021 2022 2023.. function:: window_height() 2024 2025 Return the height of the turtle window. :: 2026 2027 >>> screen.window_height() 2028 480 2029 2030 2031.. function:: window_width() 2032 2033 Return the width of the turtle window. :: 2034 2035 >>> screen.window_width() 2036 640 2037 2038 2039.. _screenspecific: 2040 2041Methods specific to Screen, not inherited from TurtleScreen 2042----------------------------------------------------------- 2043 2044.. function:: bye() 2045 2046 Shut the turtlegraphics window. 2047 2048 2049.. function:: exitonclick() 2050 2051 Bind ``bye()`` method to mouse clicks on the Screen. 2052 2053 2054 If the value "using_IDLE" in the configuration dictionary is ``False`` 2055 (default value), also enter mainloop. Remark: If IDLE with the ``-n`` switch 2056 (no subprocess) is used, this value should be set to ``True`` in 2057 :file:`turtle.cfg`. In this case IDLE's own mainloop is active also for the 2058 client script. 2059 2060 2061.. function:: setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"]) 2062 2063 Set the size and position of the main window. Default values of arguments 2064 are stored in the configuration dictionary and can be changed via a 2065 :file:`turtle.cfg` file. 2066 2067 :param width: if an integer, a size in pixels, if a float, a fraction of the 2068 screen; default is 50% of screen 2069 :param height: if an integer, the height in pixels, if a float, a fraction of 2070 the screen; default is 75% of screen 2071 :param startx: if positive, starting position in pixels from the left 2072 edge of the screen, if negative from the right edge, if ``None``, 2073 center window horizontally 2074 :param starty: if positive, starting position in pixels from the top 2075 edge of the screen, if negative from the bottom edge, if ``None``, 2076 center window vertically 2077 2078 .. doctest:: 2079 :skipif: _tkinter is None 2080 2081 >>> screen.setup (width=200, height=200, startx=0, starty=0) 2082 >>> # sets window to 200x200 pixels, in upper left of screen 2083 >>> screen.setup(width=.75, height=0.5, startx=None, starty=None) 2084 >>> # sets window to 75% of screen by 50% of screen and centers 2085 2086 2087.. function:: title(titlestring) 2088 2089 :param titlestring: a string that is shown in the titlebar of the turtle 2090 graphics window 2091 2092 Set title of turtle window to *titlestring*. 2093 2094 .. doctest:: 2095 :skipif: _tkinter is None 2096 2097 >>> screen.title("Welcome to the turtle zoo!") 2098 2099 2100Public classes 2101============== 2102 2103 2104.. class:: RawTurtle(canvas) 2105 RawPen(canvas) 2106 2107 :param canvas: a :class:`tkinter.Canvas`, a :class:`ScrolledCanvas` or a 2108 :class:`TurtleScreen` 2109 2110 Create a turtle. The turtle has all methods described above as "methods of 2111 Turtle/RawTurtle". 2112 2113 2114.. class:: Turtle() 2115 2116 Subclass of RawTurtle, has the same interface but draws on a default 2117 :class:`Screen` object created automatically when needed for the first time. 2118 2119 2120.. class:: TurtleScreen(cv) 2121 2122 :param cv: a :class:`tkinter.Canvas` 2123 2124 Provides screen oriented methods like :func:`setbg` etc. that are described 2125 above. 2126 2127.. class:: Screen() 2128 2129 Subclass of TurtleScreen, with :ref:`four methods added <screenspecific>`. 2130 2131 2132.. class:: ScrolledCanvas(master) 2133 2134 :param master: some Tkinter widget to contain the ScrolledCanvas, i.e. 2135 a Tkinter-canvas with scrollbars added 2136 2137 Used by class Screen, which thus automatically provides a ScrolledCanvas as 2138 playground for the turtles. 2139 2140.. class:: Shape(type_, data) 2141 2142 :param type\_: one of the strings "polygon", "image", "compound" 2143 2144 Data structure modeling shapes. The pair ``(type_, data)`` must follow this 2145 specification: 2146 2147 2148 =========== =========== 2149 *type_* *data* 2150 =========== =========== 2151 "polygon" a polygon-tuple, i.e. a tuple of pairs of coordinates 2152 "image" an image (in this form only used internally!) 2153 "compound" ``None`` (a compound shape has to be constructed using the 2154 :meth:`addcomponent` method) 2155 =========== =========== 2156 2157 .. method:: addcomponent(poly, fill, outline=None) 2158 2159 :param poly: a polygon, i.e. a tuple of pairs of numbers 2160 :param fill: a color the *poly* will be filled with 2161 :param outline: a color for the poly's outline (if given) 2162 2163 Example: 2164 2165 .. doctest:: 2166 :skipif: _tkinter is None 2167 2168 >>> poly = ((0,0),(10,-5),(0,10),(-10,-5)) 2169 >>> s = Shape("compound") 2170 >>> s.addcomponent(poly, "red", "blue") 2171 >>> # ... add more components and then use register_shape() 2172 2173 See :ref:`compoundshapes`. 2174 2175 2176.. class:: Vec2D(x, y) 2177 2178 A two-dimensional vector class, used as a helper class for implementing 2179 turtle graphics. May be useful for turtle graphics programs too. Derived 2180 from tuple, so a vector is a tuple! 2181 2182 Provides (for *a*, *b* vectors, *k* number): 2183 2184 * ``a + b`` vector addition 2185 * ``a - b`` vector subtraction 2186 * ``a * b`` inner product 2187 * ``k * a`` and ``a * k`` multiplication with scalar 2188 * ``abs(a)`` absolute value of a 2189 * ``a.rotate(angle)`` rotation 2190 2191 2192Help and configuration 2193====================== 2194 2195How to use help 2196--------------- 2197 2198The public methods of the Screen and Turtle classes are documented extensively 2199via docstrings. So these can be used as online-help via the Python help 2200facilities: 2201 2202- When using IDLE, tooltips show the signatures and first lines of the 2203 docstrings of typed in function-/method calls. 2204 2205- Calling :func:`help` on methods or functions displays the docstrings:: 2206 2207 >>> help(Screen.bgcolor) 2208 Help on method bgcolor in module turtle: 2209 2210 bgcolor(self, *args) unbound turtle.Screen method 2211 Set or return backgroundcolor of the TurtleScreen. 2212 2213 Arguments (if given): a color string or three numbers 2214 in the range 0..colormode or a 3-tuple of such numbers. 2215 2216 2217 >>> screen.bgcolor("orange") 2218 >>> screen.bgcolor() 2219 "orange" 2220 >>> screen.bgcolor(0.5,0,0.5) 2221 >>> screen.bgcolor() 2222 "#800080" 2223 2224 >>> help(Turtle.penup) 2225 Help on method penup in module turtle: 2226 2227 penup(self) unbound turtle.Turtle method 2228 Pull the pen up -- no drawing when moving. 2229 2230 Aliases: penup | pu | up 2231 2232 No argument 2233 2234 >>> turtle.penup() 2235 2236- The docstrings of the functions which are derived from methods have a modified 2237 form:: 2238 2239 >>> help(bgcolor) 2240 Help on function bgcolor in module turtle: 2241 2242 bgcolor(*args) 2243 Set or return backgroundcolor of the TurtleScreen. 2244 2245 Arguments (if given): a color string or three numbers 2246 in the range 0..colormode or a 3-tuple of such numbers. 2247 2248 Example:: 2249 2250 >>> bgcolor("orange") 2251 >>> bgcolor() 2252 "orange" 2253 >>> bgcolor(0.5,0,0.5) 2254 >>> bgcolor() 2255 "#800080" 2256 2257 >>> help(penup) 2258 Help on function penup in module turtle: 2259 2260 penup() 2261 Pull the pen up -- no drawing when moving. 2262 2263 Aliases: penup | pu | up 2264 2265 No argument 2266 2267 Example: 2268 >>> penup() 2269 2270These modified docstrings are created automatically together with the function 2271definitions that are derived from the methods at import time. 2272 2273 2274Translation of docstrings into different languages 2275-------------------------------------------------- 2276 2277There is a utility to create a dictionary the keys of which are the method names 2278and the values of which are the docstrings of the public methods of the classes 2279Screen and Turtle. 2280 2281.. function:: write_docstringdict(filename="turtle_docstringdict") 2282 2283 :param filename: a string, used as filename 2284 2285 Create and write docstring-dictionary to a Python script with the given 2286 filename. This function has to be called explicitly (it is not used by the 2287 turtle graphics classes). The docstring dictionary will be written to the 2288 Python script :file:`{filename}.py`. It is intended to serve as a template 2289 for translation of the docstrings into different languages. 2290 2291If you (or your students) want to use :mod:`turtle` with online help in your 2292native language, you have to translate the docstrings and save the resulting 2293file as e.g. :file:`turtle_docstringdict_german.py`. 2294 2295If you have an appropriate entry in your :file:`turtle.cfg` file this dictionary 2296will be read in at import time and will replace the original English docstrings. 2297 2298At the time of this writing there are docstring dictionaries in German and in 2299Italian. (Requests please to glingl@aon.at.) 2300 2301 2302 2303How to configure Screen and Turtles 2304----------------------------------- 2305 2306The built-in default configuration mimics the appearance and behaviour of the 2307old turtle module in order to retain best possible compatibility with it. 2308 2309If you want to use a different configuration which better reflects the features 2310of this module or which better fits to your needs, e.g. for use in a classroom, 2311you can prepare a configuration file ``turtle.cfg`` which will be read at import 2312time and modify the configuration according to its settings. 2313 2314The built in configuration would correspond to the following turtle.cfg:: 2315 2316 width = 0.5 2317 height = 0.75 2318 leftright = None 2319 topbottom = None 2320 canvwidth = 400 2321 canvheight = 300 2322 mode = standard 2323 colormode = 1.0 2324 delay = 10 2325 undobuffersize = 1000 2326 shape = classic 2327 pencolor = black 2328 fillcolor = black 2329 resizemode = noresize 2330 visible = True 2331 language = english 2332 exampleturtle = turtle 2333 examplescreen = screen 2334 title = Python Turtle Graphics 2335 using_IDLE = False 2336 2337Short explanation of selected entries: 2338 2339- The first four lines correspond to the arguments of the :meth:`Screen.setup` 2340 method. 2341- Line 5 and 6 correspond to the arguments of the method 2342 :meth:`Screen.screensize`. 2343- *shape* can be any of the built-in shapes, e.g: arrow, turtle, etc. For more 2344 info try ``help(shape)``. 2345- If you want to use no fillcolor (i.e. make the turtle transparent), you have 2346 to write ``fillcolor = ""`` (but all nonempty strings must not have quotes in 2347 the cfg-file). 2348- If you want to reflect the turtle its state, you have to use ``resizemode = 2349 auto``. 2350- If you set e.g. ``language = italian`` the docstringdict 2351 :file:`turtle_docstringdict_italian.py` will be loaded at import time (if 2352 present on the import path, e.g. in the same directory as :mod:`turtle`. 2353- The entries *exampleturtle* and *examplescreen* define the names of these 2354 objects as they occur in the docstrings. The transformation of 2355 method-docstrings to function-docstrings will delete these names from the 2356 docstrings. 2357- *using_IDLE*: Set this to ``True`` if you regularly work with IDLE and its -n 2358 switch ("no subprocess"). This will prevent :func:`exitonclick` to enter the 2359 mainloop. 2360 2361There can be a :file:`turtle.cfg` file in the directory where :mod:`turtle` is 2362stored and an additional one in the current working directory. The latter will 2363override the settings of the first one. 2364 2365The :file:`Lib/turtledemo` directory contains a :file:`turtle.cfg` file. You can 2366study it as an example and see its effects when running the demos (preferably 2367not from within the demo-viewer). 2368 2369 2370:mod:`turtledemo` --- Demo scripts 2371================================== 2372 2373.. module:: turtledemo 2374 :synopsis: A viewer for example turtle scripts 2375 2376The :mod:`turtledemo` package includes a set of demo scripts. These 2377scripts can be run and viewed using the supplied demo viewer as follows:: 2378 2379 python -m turtledemo 2380 2381Alternatively, you can run the demo scripts individually. For example, :: 2382 2383 python -m turtledemo.bytedesign 2384 2385The :mod:`turtledemo` package directory contains: 2386 2387- A demo viewer :file:`__main__.py` which can be used to view the sourcecode 2388 of the scripts and run them at the same time. 2389- Multiple scripts demonstrating different features of the :mod:`turtle` 2390 module. Examples can be accessed via the Examples menu. They can also 2391 be run standalone. 2392- A :file:`turtle.cfg` file which serves as an example of how to write 2393 and use such files. 2394 2395The demo scripts are: 2396 2397.. tabularcolumns:: |l|L|L| 2398 2399+----------------+------------------------------+-----------------------+ 2400| Name | Description | Features | 2401+================+==============================+=======================+ 2402| bytedesign | complex classical | :func:`tracer`, delay,| 2403| | turtle graphics pattern | :func:`update` | 2404+----------------+------------------------------+-----------------------+ 2405| chaos | graphs Verhulst dynamics, | world coordinates | 2406| | shows that computer's | | 2407| | computations can generate | | 2408| | results sometimes against the| | 2409| | common sense expectations | | 2410+----------------+------------------------------+-----------------------+ 2411| clock | analog clock showing time | turtles as clock's | 2412| | of your computer | hands, ontimer | 2413+----------------+------------------------------+-----------------------+ 2414| colormixer | experiment with r, g, b | :func:`ondrag` | 2415+----------------+------------------------------+-----------------------+ 2416| forest | 3 breadth-first trees | randomization | 2417+----------------+------------------------------+-----------------------+ 2418| fractalcurves | Hilbert & Koch curves | recursion | 2419+----------------+------------------------------+-----------------------+ 2420| lindenmayer | ethnomathematics | L-System | 2421| | (indian kolams) | | 2422+----------------+------------------------------+-----------------------+ 2423| minimal_hanoi | Towers of Hanoi | Rectangular Turtles | 2424| | | as Hanoi discs | 2425| | | (shape, shapesize) | 2426+----------------+------------------------------+-----------------------+ 2427| nim | play the classical nim game | turtles as nimsticks, | 2428| | with three heaps of sticks | event driven (mouse, | 2429| | against the computer. | keyboard) | 2430+----------------+------------------------------+-----------------------+ 2431| paint | super minimalistic | :func:`onclick` | 2432| | drawing program | | 2433+----------------+------------------------------+-----------------------+ 2434| peace | elementary | turtle: appearance | 2435| | | and animation | 2436+----------------+------------------------------+-----------------------+ 2437| penrose | aperiodic tiling with | :func:`stamp` | 2438| | kites and darts | | 2439+----------------+------------------------------+-----------------------+ 2440| planet_and_moon| simulation of | compound shapes, | 2441| | gravitational system | :class:`Vec2D` | 2442+----------------+------------------------------+-----------------------+ 2443| round_dance | dancing turtles rotating | compound shapes, clone| 2444| | pairwise in opposite | shapesize, tilt, | 2445| | direction | get_shapepoly, update | 2446+----------------+------------------------------+-----------------------+ 2447| sorting_animate| visual demonstration of | simple alignment, | 2448| | different sorting methods | randomization | 2449+----------------+------------------------------+-----------------------+ 2450| tree | a (graphical) breadth | :func:`clone` | 2451| | first tree (using generators)| | 2452+----------------+------------------------------+-----------------------+ 2453| two_canvases | simple design | turtles on two | 2454| | | canvases | 2455+----------------+------------------------------+-----------------------+ 2456| wikipedia | a pattern from the wikipedia | :func:`clone`, | 2457| | article on turtle graphics | :func:`undo` | 2458+----------------+------------------------------+-----------------------+ 2459| yinyang | another elementary example | :func:`circle` | 2460+----------------+------------------------------+-----------------------+ 2461 2462Have fun! 2463 2464 2465Changes since Python 2.6 2466======================== 2467 2468- The methods :meth:`Turtle.tracer`, :meth:`Turtle.window_width` and 2469 :meth:`Turtle.window_height` have been eliminated. 2470 Methods with these names and functionality are now available only 2471 as methods of :class:`Screen`. The functions derived from these remain 2472 available. (In fact already in Python 2.6 these methods were merely 2473 duplications of the corresponding 2474 :class:`TurtleScreen`/:class:`Screen`-methods.) 2475 2476- The method :meth:`Turtle.fill` has been eliminated. 2477 The behaviour of :meth:`begin_fill` and :meth:`end_fill` 2478 have changed slightly: now every filling-process must be completed with an 2479 ``end_fill()`` call. 2480 2481- A method :meth:`Turtle.filling` has been added. It returns a boolean 2482 value: ``True`` if a filling process is under way, ``False`` otherwise. 2483 This behaviour corresponds to a ``fill()`` call without arguments in 2484 Python 2.6. 2485 2486Changes since Python 3.0 2487======================== 2488 2489- The methods :meth:`Turtle.shearfactor`, :meth:`Turtle.shapetransform` and 2490 :meth:`Turtle.get_shapepoly` have been added. Thus the full range of 2491 regular linear transforms is now available for transforming turtle shapes. 2492 :meth:`Turtle.tiltangle` has been enhanced in functionality: it now can 2493 be used to get or set the tiltangle. :meth:`Turtle.settiltangle` has been 2494 deprecated. 2495 2496- The method :meth:`Screen.onkeypress` has been added as a complement to 2497 :meth:`Screen.onkey` which in fact binds actions to the keyrelease event. 2498 Accordingly the latter has got an alias: :meth:`Screen.onkeyrelease`. 2499 2500- The method :meth:`Screen.mainloop` has been added. So when working only 2501 with Screen and Turtle objects one must not additionally import 2502 :func:`mainloop` anymore. 2503 2504- Two input methods has been added :meth:`Screen.textinput` and 2505 :meth:`Screen.numinput`. These popup input dialogs and return 2506 strings and numbers respectively. 2507 2508- Two example scripts :file:`tdemo_nim.py` and :file:`tdemo_round_dance.py` 2509 have been added to the :file:`Lib/turtledemo` directory. 2510 2511 2512.. doctest:: 2513 :skipif: _tkinter is None 2514 :hide: 2515 2516 >>> for turtle in turtles(): 2517 ... turtle.reset() 2518 >>> turtle.penup() 2519 >>> turtle.goto(-200,25) 2520 >>> turtle.pendown() 2521 >>> turtle.write("No one expects the Spanish Inquisition!", 2522 ... font=("Arial", 20, "normal")) 2523 >>> turtle.penup() 2524 >>> turtle.goto(-100,-50) 2525 >>> turtle.pendown() 2526 >>> turtle.write("Our two chief Turtles are...", 2527 ... font=("Arial", 16, "normal")) 2528 >>> turtle.penup() 2529 >>> turtle.goto(-450,-75) 2530 >>> turtle.write(str(turtles())) 2531