blob: 354bb1114dc3ee737b6a0dcf79c768828050958d [file] [log] [blame]
: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).
.. versionadded:: 2.5
.. function:: delay(delay)
Set the speed of the turtle to *delay*, which is given in ms.
.. versionadded:: 2.5
.. 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.
.. versionadded:: 2.5
.. function:: end_fill()
End filling mode, and fill the shape; equivalent to ``fill(0)``.
.. versionadded:: 2.5
.. 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.
.. versionadded:: 2.5
.. function:: heading()
Return the current orientation of the turtle.
.. versionadded:: 2.3
.. function:: setheading(angle)
Set the orientation of the turtle to *angle*.
.. versionadded:: 2.3
.. function:: position()
Return the current location of the turtle as an ``(x,y)`` pair.
.. versionadded:: 2.3
.. function:: setx(x)
Set the x coordinate of the turtle to *x*.
.. versionadded:: 2.3
.. function:: sety(y)
Set the y coordinate of the turtle to *y*.
.. versionadded:: 2.3
.. function:: window_width()
Return the width of the canvas window.
.. versionadded:: 2.3
.. function:: window_height()
Return the height of the canvas window.
.. versionadded:: 2.3
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.