\section{\module{turtle} ---         Turtle graphics for Tk} \declaremodule{standard}{turtle}   \platform{Tk}\moduleauthor{Guido van Rossum}{guido@python.org}\modulesynopsis{An environment for turtle graphics.} \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}  The \module{turtle} module provides turtle graphics primitives, in both anobject-oriented and procedure-oriented ways. Because it uses \module{Tkinter}for the underlying graphics, it needs a version of python installed withTk support. The procedural interface uses a pen and a canvas which are automagicallycreated when any of the functions are called. The \module{turtle} module defines the following functions: \begin{funcdesc}{degrees}{}Set angle measurement units to degrees.\end{funcdesc} \begin{funcdesc}{radians}{}Set angle measurement units to radians.\end{funcdesc} \begin{funcdesc}{setup}{**kwargs}Sets the size and position of the main window.  Keywords are:\begin{itemize}  \item \code{width}: either a size in pixels or a fraction of the screen.   The default is 50\% of the screen.  \item \code{height}: either a size in pixels or a fraction of the screen.   The default is 50\% of the screen.  \item \code{startx}: starting position in pixels from the left edge      of the screen. \code{None} is the default value and       centers the window horizontally on screen.  \item \code{starty}: starting position in pixels from the top edge      of the screen. \code{None} is the default value and       centers the window vertically on screen.\end{itemize}    Examples: \begin{verbatim}# Uses default geometry: 50% x 50% of screen, centered.setup()   # Sets window to 200x200 pixels, in upper left of screensetup (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)\end{verbatim} \end{funcdesc} \begin{funcdesc}{title}{title_str}Set the window's title to \var{title}.\end{funcdesc} \begin{funcdesc}{done}{}Enters the Tk main loop.  The window will continue to be displayed until the user closes it or the process is killed.\end{funcdesc} \begin{funcdesc}{reset}{}Clear the screen, re-center the pen, and set variables to the defaultvalues.\end{funcdesc} \begin{funcdesc}{clear}{}Clear the screen.\end{funcdesc} \begin{funcdesc}{tracer}{flag}Set tracing on/off (according to whether flag is true or not). Tracingmeans line are drawn more slowly, with an animation of an arrow along the line.\end{funcdesc} \begin{funcdesc}{speed}{speed}Set the speed of the turtle. Valid values for the parameter\var{speed} are \code{'fastest'} (no delay), \code{'fast'},(delay 5ms), \code{'normal'} (delay 10ms), \code{'slow'}(delay 15ms), and \code{'slowest'} (delay 20ms).\versionadded{2.5}\end{funcdesc} \begin{funcdesc}{delay}{delay}Set the speed of the turtle to \var{delay}, which is givenin ms. \versionadded{2.5}\end{funcdesc} \begin{funcdesc}{forward}{distance}Go forward \var{distance} steps.\end{funcdesc} \begin{funcdesc}{backward}{distance}Go backward \var{distance} steps.\end{funcdesc} \begin{funcdesc}{left}{angle}Turn left \var{angle} units. Units are by default degrees, but can beset via the \function{degrees()} and \function{radians()} functions.\end{funcdesc} \begin{funcdesc}{right}{angle}Turn right \var{angle} units. Units are by default degrees, but can beset via the \function{degrees()} and \function{radians()} functions.\end{funcdesc} \begin{funcdesc}{up}{}Move the pen up --- stop drawing.\end{funcdesc} \begin{funcdesc}{down}{}Move the pen down --- draw when moving.\end{funcdesc} \begin{funcdesc}{width}{width}Set the line width to \var{width}.\end{funcdesc} \begin{funcdesc}{color}{s}\funclineni{color}{(r, g, b)}\funclineni{color}{r, g, b}Set the pen color.  In the first form, the color is specified as aTk color specification as a string.  The second form specifies thecolor as a tuple of the RGB values, each in the range [0..1].  For thethird form, the color is specified giving the RGB values as threeseparate parameters (each in the range [0..1]).\end{funcdesc} \begin{funcdesc}{write}{text\optional{, move}}Write \var{text} at the current pen position. If \var{move} is true,the pen is moved to the bottom-right corner of the text. By default,\var{move} is false.\end{funcdesc} \begin{funcdesc}{fill}{flag}The complete specifications are rather complex, but the recommended usage is: call \code{fill(1)} before drawing a path you want to fill,and call \code{fill(0)} when you finish to draw the path.\end{funcdesc} \begin{funcdesc}{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}\end{funcdesc} \begin{funcdesc}{end\_fill}{}End filling mode, and fill the shape; equivalent to \code{fill(0)}.\versionadded{2.5}\end{funcdesc} \begin{funcdesc}{circle}{radius\optional{, extent}}Draw a circle with radius \var{radius} whose center-point is\var{radius} units left of the turtle.\var{extent} determines which part of a circle is drawn: ifnot given it defaults to a full circle. If \var{extent} is not a full circle, one endpoint of the arc is thecurrent pen position. The arc is drawn in a counter clockwisedirection if \var{radius} is positive, otherwise in a clockwisedirection.  In the process, the direction of the turtle is changedby the amount of the \var{extent}.\end{funcdesc} \begin{funcdesc}{goto}{x, y}\funclineni{goto}{(x, y)}Go to co-ordinates \var{x}, \var{y}.  The co-ordinates may bespecified either as two separate arguments or as a 2-tuple.\end{funcdesc} \begin{funcdesc}{towards}{x, y}Return the angle of the line from the turtle's positionto the point \var{x}, \var{y}. The co-ordinates may bespecified either as two separate arguments, as a 2-tuple,or as another pen object.\versionadded{2.5}\end{funcdesc} \begin{funcdesc}{heading}{}Return the current orientation of the turtle.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{setheading}{angle}Set the orientation of the turtle to \var{angle}.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{position}{}Return the current location of the turtle as an \code{(x,y)} pair.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{setx}{x}Set the x coordinate of the turtle to \var{x}.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{sety}{y}Set the y coordinate of the turtle to \var{y}.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{window\_width}{}Return the width of the canvas window.\versionadded{2.3}\end{funcdesc} \begin{funcdesc}{window\_height}{}Return the height of the canvas window.\versionadded{2.3}\end{funcdesc} This module also does \code{from math import *}, so see thedocumentation for the \refmodule{math} module for additional constantsand functions useful for turtle graphics. \begin{funcdesc}{demo}{}Exercise the module a bit.\end{funcdesc} \begin{excdesc}{Error}Exception raised on any error caught by this module.\end{excdesc} For examples, see the code of the \function{demo()} function. This module defines the following classes: \begin{classdesc}{Pen}{}Define a pen. All above functions can be called as a methods on the givenpen. The constructor automatically creates a canvas do be drawn on.\end{classdesc} \begin{classdesc}{Turtle}{}Define a pen. This is essentially a synonym for \code{Pen()};\class{Turtle} is an empty subclass of \class{Pen}.\end{classdesc} \begin{classdesc}{RawPen}{canvas}Define a pen which draws on a canvas \var{canvas}. This is useful if you want to use the module to create graphics in a ``real'' program.\end{classdesc} \subsection{Turtle, Pen and RawPen Objects \label{pen-rawpen-objects}} Most of the global functions available in the module are alsoavailable 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\function{degrees()}, which takes an optional argument letting you specify the number of units corresponding to a full circle: \begin{methoddesc}{degrees}{\optional{fullcircle}}\var{fullcircle} is by default 360. This can cause the pen to have anyangular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or400 for gradians.\end{methoddesc}