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