| |
| :mod:`turtle` --- Turtle graphics for Tk |
| ======================================== |
| |
| .. module:: turtle |
| :platform: Tk |
| :synopsis: An environment for turtle graphics. |
| .. moduleauthor:: Guido van Rossum <guido@python.org> |
| |
| |
| .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| |
| |
| The :mod:`turtle` module provides turtle graphics primitives, in both an |
| object-oriented and procedure-oriented ways. Because it uses :mod:`Tkinter` for |
| the underlying graphics, it needs a version of python installed with Tk support. |
| |
| The procedural interface uses a pen and a canvas which are automagically created |
| when any of the functions are called. |
| |
| The :mod:`turtle` module defines the following functions: |
| |
| |
| .. function:: degrees() |
| |
| Set angle measurement units to degrees. |
| |
| |
| .. function:: radians() |
| |
| Set angle measurement units to radians. |
| |
| |
| .. function:: setup(**kwargs) |
| |
| Sets the size and position of the main window. Keywords are: |
| |
| * ``width``: either a size in pixels or a fraction of the screen. The default is |
| 50% of the screen. |
| |
| * ``height``: either a size in pixels or a fraction of the screen. The default |
| is 50% of the screen. |
| |
| * ``startx``: starting position in pixels from the left edge of the screen. |
| ``None`` is the default value and centers the window horizontally on screen. |
| |
| * ``starty``: starting position in pixels from the top edge of the screen. |
| ``None`` is the default value and centers the window vertically on screen. |
| |
| Examples:: |
| |
| # Uses default geometry: 50% x 50% of screen, centered. |
| setup() |
| |
| # Sets window to 200x200 pixels, in upper left of screen |
| setup (width=200, height=200, startx=0, starty=0) |
| |
| # Sets window to 75% of screen by 50% of screen, and centers it. |
| setup(width=.75, height=0.5, startx=None, starty=None) |
| |
| |
| .. function:: title(title_str) |
| |
| Set the window's title to *title*. |
| |
| |
| .. function:: done() |
| |
| Enters the Tk main loop. The window will continue to be displayed until the |
| user closes it or the process is killed. |
| |
| |
| .. function:: reset() |
| |
| Clear the screen, re-center the pen, and set variables to the default values. |
| |
| |
| .. function:: clear() |
| |
| Clear the screen. |
| |
| |
| .. function:: tracer(flag) |
| |
| Set tracing on/off (according to whether flag is true or not). Tracing means |
| line are drawn more slowly, with an animation of an arrow along the line. |
| |
| |
| .. function:: speed(speed) |
| |
| Set the speed of the turtle. Valid values for the parameter *speed* are |
| ``'fastest'`` (no delay), ``'fast'``, (delay 5ms), ``'normal'`` (delay 10ms), |
| ``'slow'`` (delay 15ms), and ``'slowest'`` (delay 20ms). |
| |
| |
| .. function:: delay(delay) |
| |
| Set the speed of the turtle to *delay*, which is given in ms. |
| |
| |
| .. function:: forward(distance) |
| |
| Go forward *distance* steps. |
| |
| |
| .. function:: backward(distance) |
| |
| Go backward *distance* steps. |
| |
| |
| .. function:: left(angle) |
| |
| Turn left *angle* units. Units are by default degrees, but can be set via the |
| :func:`degrees` and :func:`radians` functions. |
| |
| |
| .. function:: right(angle) |
| |
| Turn right *angle* units. Units are by default degrees, but can be set via the |
| :func:`degrees` and :func:`radians` functions. |
| |
| |
| .. function:: up() |
| |
| Move the pen up --- stop drawing. |
| |
| |
| .. function:: down() |
| |
| Move the pen down --- draw when moving. |
| |
| |
| .. function:: width(width) |
| |
| Set the line width to *width*. |
| |
| |
| .. function:: color(s) |
| color((r, g, b)) |
| color(r, g, b) |
| |
| Set the pen color. In the first form, the color is specified as a Tk color |
| specification as a string. The second form specifies the color as a tuple of |
| the RGB values, each in the range [0..1]. For the third form, the color is |
| specified giving the RGB values as three separate parameters (each in the range |
| [0..1]). |
| |
| |
| .. function:: write(text[, move]) |
| |
| Write *text* at the current pen position. If *move* is true, the pen is moved to |
| the bottom-right corner of the text. By default, *move* is false. |
| |
| |
| .. function:: fill(flag) |
| |
| The complete specifications are rather complex, but the recommended usage is: |
| call ``fill(1)`` before drawing a path you want to fill, and call ``fill(0)`` |
| when you finish to draw the path. |
| |
| |
| .. function:: begin_fill() |
| |
| Switch turtle into filling mode; Must eventually be followed by a corresponding |
| end_fill() call. Otherwise it will be ignored. |
| |
| |
| .. function:: end_fill() |
| |
| End filling mode, and fill the shape; equivalent to ``fill(0)``. |
| |
| |
| .. function:: circle(radius[, extent]) |
| |
| Draw a circle with radius *radius* whose center-point is *radius* units left of |
| the turtle. *extent* determines which part of a circle is drawn: if not given it |
| defaults to a full circle. |
| |
| If *extent* is not a full circle, one endpoint of the arc is the current pen |
| position. The arc is drawn in a counter clockwise direction if *radius* is |
| positive, otherwise in a clockwise direction. In the process, the direction of |
| the turtle is changed by the amount of the *extent*. |
| |
| |
| .. function:: goto(x, y) |
| goto((x, y)) |
| |
| Go to co-ordinates *x*, *y*. The co-ordinates may be specified either as two |
| separate arguments or as a 2-tuple. |
| |
| |
| .. function:: towards(x, y) |
| |
| Return the angle of the line from the turtle's position to the point *x*, *y*. |
| The co-ordinates may be specified either as two separate arguments, as a |
| 2-tuple, or as another pen object. |
| |
| |
| .. function:: heading() |
| |
| Return the current orientation of the turtle. |
| |
| |
| .. function:: setheading(angle) |
| |
| Set the orientation of the turtle to *angle*. |
| |
| |
| .. function:: position() |
| |
| Return the current location of the turtle as an ``(x,y)`` pair. |
| |
| |
| .. function:: setx(x) |
| |
| Set the x coordinate of the turtle to *x*. |
| |
| |
| .. function:: sety(y) |
| |
| Set the y coordinate of the turtle to *y*. |
| |
| |
| .. function:: window_width() |
| |
| Return the width of the canvas window. |
| |
| |
| .. function:: window_height() |
| |
| Return the height of the canvas window. |
| |
| |
| This module also does ``from math import *``, so see the documentation for the |
| :mod:`math` module for additional constants and functions useful for turtle |
| graphics. |
| |
| |
| .. function:: demo() |
| |
| Exercise the module a bit. |
| |
| |
| .. exception:: Error |
| |
| Exception raised on any error caught by this module. |
| |
| For examples, see the code of the :func:`demo` function. |
| |
| This module defines the following classes: |
| |
| |
| .. class:: Pen() |
| |
| Define a pen. All above functions can be called as a methods on the given pen. |
| The constructor automatically creates a canvas do be drawn on. |
| |
| |
| .. class:: Turtle() |
| |
| Define a pen. This is essentially a synonym for ``Pen()``; :class:`Turtle` is an |
| empty subclass of :class:`Pen`. |
| |
| |
| .. class:: RawPen(canvas) |
| |
| Define a pen which draws on a canvas *canvas*. This is useful if you want to |
| use the module to create graphics in a "real" program. |
| |
| |
| .. _pen-rawpen-objects: |
| |
| Turtle, Pen and RawPen Objects |
| ------------------------------ |
| |
| Most of the global functions available in the module are also available as |
| methods of the :class:`Turtle`, :class:`Pen` and :class:`RawPen` classes, |
| affecting only the state of the given pen. |
| |
| The only method which is more powerful as a method is :func:`degrees`, which |
| takes an optional argument letting you specify the number of units |
| corresponding to a full circle: |
| |
| |
| .. method:: Turtle.degrees([fullcircle]) |
| |
| *fullcircle* is by default 360. This can cause the pen to have any angular units |
| whatever: give *fullcircle* 2\*$π for radians, or 400 for gradians. |
| |