source: trunk/essentials/dev-lang/python/Doc/lib/libturtle.tex@ 3368

\section{\module{turtle} ---
         Turtle graphics for Tk}

\declaremodule{standard}{turtle}
   \platform{Tk}
\moduleauthor{Guido van Rossum}{[email protected]}
\modulesynopsis{An environment for turtle graphics.}

\sectionauthor{Moshe Zadka}{[email protected]}


The \module{turtle} module provides turtle graphics primitives, in both an
object-oriented and procedure-oriented ways. Because it uses \module{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 \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 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)
\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 default
values.
\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). Tracing
means 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 given
in 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 be
set 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 be
set 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 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]).
\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.