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