Doc/lib/libturtle.tex

   1 \section{\module{turtle} ---
   2          Turtle graphics for Tk}
   3
   4 \declaremodule{standard}{turtle}
   5    \platform{Tk}
   6 \moduleauthor{Guido van Rossum}{guido@python.org}
   7 \modulesynopsis{An environment for turtle graphics.}
   8
   9 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
  10
  11
  12 The \module{turtle} module provides turtle graphics primitives, in both an
  13 object-oriented and procedure-oriented ways. Because it uses \module{Tkinter}
  14 for the underlying graphics, it needs a version of python installed with
  15 Tk support.
  16
  17 The procedural interface uses a pen and a canvas which are automagically
  18 created when any of the functions are called.
  19
  20 The \module{turtle} module defines the following functions:
  21
  22 \begin{funcdesc}{degrees}{}
  23 Set angle measurement units to degrees.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{radians}{}
  27 Set angle measurement units to radians.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{reset}{}
  31 Clear the screen, re-center the pen, and set variables to the default
  32 values.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{clear}{}
  36 Clear the screen.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{tracer}{flag}
  40 Set tracing on/off (according to whether flag is true or not). Tracing
  41 means line are drawn more slowly, with an animation of an arrow along the
  42 line.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{forward}{distance}
  46 Go forward \var{distance} steps.
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{backward}{distance}
  50 Go backward \var{distance} steps.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{left}{angle}
  54 Turn left \var{angle} units. Units are by default degrees, but can be
  55 set via the \function{degrees()} and \function{radians()} functions.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{right}{angle}
  59 Turn right \var{angle} units. Units are by default degrees, but can be
  60 set via the \function{degrees()} and \function{radians()} functions.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{up}{}
  64 Move the pen up --- stop drawing.
  65 \end{funcdesc}
  66
  67 \begin{funcdesc}{down}{}
  68 Move the pen down --- draw when moving.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{width}{width}
  72 Set the line width to \var{width}.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{color}{s}
  76 \funclineni{color}{(r, g, b)}
  77 \funclineni{color}{r, g, b}
  78 Set the pen color.  In the first form, the color is specified as a
  79 Tk color specification as a string.  The second form specifies the
  80 color as a tuple of the RGB values, each in the range [0..1].  For the
  81 third form, the color is specified giving the RGB values as three
  82 separate parameters (each in the range [0..1]).
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{write}{text\optional{, move}}
  86 Write \var{text} at the current pen position. If \var{move} is true,
  87 the pen is moved to the bottom-right corner of the text. By default,
  88 \var{move} is false.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{fill}{flag}
  92 The complete specifications are rather complex, but the recommended
  93 usage is: call \code{fill(1)} before drawing a path you want to fill,
  94 and call \code{fill(0)} when you finish to draw the path.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{circle}{radius\optional{, extent}}
  98 Draw a circle with radius \var{radius} whose center-point is
  99 \var{radius} units left of the turtle.
 100 \var{extent} determines which part of a circle is drawn: if
 101 not given it defaults to a full circle.
 102
 103 If \var{extent} is not a full circle, one endpoint of the arc is the
 104 current pen position. The arc is drawn in a counter clockwise
 105 direction if \var{radius} is positive, otherwise in a clockwise
 106 direction.  In the process, the direction of the turtle is changed
 107 by the amount of the \var{extent}.
 108 \end{funcdesc}
 109
 110 \begin{funcdesc}{goto}{x, y}
 111 \funclineni{goto}{(x, y)}
 112 Go to co-ordinates \var{x}, \var{y}.  The co-ordinates may be
 113 specified either as two separate arguments or as a 2-tuple.
 114 \end{funcdesc}
 115
 116 This module also does \code{from math import *}, so see the
 117 documentation for the \refmodule{math} module for additional constants
 118 and functions useful for turtle graphics.
 119
 120 \begin{funcdesc}{demo}{}
 121 Exercise the module a bit.
 122 \end{funcdesc}
 123
 124 \begin{excdesc}{Error}
 125 Exception raised on any error caught by this module.
 126 \end{excdesc}
 127
 128 For examples, see the code of the \function{demo()} function.
 129
 130 This module defines the following classes:
 131
 132 \begin{classdesc}{Pen}{}
 133 Define a pen. All above functions can be called as a methods on the given
 134 pen. The constructor automatically creates a canvas do be drawn on.
 135 \end{classdesc}
 136
 137 \begin{classdesc}{RawPen}{canvas}
 138 Define a pen which draws on a canvas \var{canvas}. This is useful if
 139 you want to use the module to create graphics in a ``real'' program.
 140 \end{classdesc}
 141
 142 \subsection{Pen and RawPen Objects \label{pen-rawpen-objects}}
 143
 144 \class{Pen} and \class{RawPen} objects have all the global functions
 145 described above, except for \function{demo()} as methods, which
 146 manipulate the given pen.
 147
 148 The only method which is more powerful as a method is
 149 \function{degrees()}.
 150
 151 \begin{methoddesc}{degrees}{\optional{fullcircle}}
 152 \var{fullcircle} is by default 360. This can cause the pen to have any
 153 angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or
 154 400 for gradians.
 155 \end{methoddesc}