313 lines
7.6 KiB
ReStructuredText
313 lines
7.6 KiB
ReStructuredText
|
|
: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*pi`` for radians, or 400 for gradians.
|
|
|