:mod:`turtle` --- Turtle graphics for Tk ======================================== .. module:: turtle :platform: Tk :synopsis: An environment for turtle graphics. .. moduleauthor:: Guido van Rossum .. sectionauthor:: Moshe Zadka 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.