summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libturtle.tex
blob: 638bc076bb908ebb97d50bf10710fcae6d359871 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
\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 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}{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}{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}{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: if
not given it defaults to a full circle.

If \var{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 \var{radius} is positive, otherwise in a clockwise
direction.  In the process, the direction of the turtle is changed
by 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 be
specified either as two separate arguments or as a 2-tuple.
\end{funcdesc}

This module also does \code{from math import *}, so see the
documentation for the \refmodule{math} module for additional constants
and 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 given
pen. The constructor automatically creates a canvas do be drawn on.
\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{Pen and RawPen Objects \label{pen-rawpen-objects}}

\class{Pen} and \class{RawPen} objects have all the global functions
described above, except for \function{demo()} as methods, which
manipulate the given pen.

The only method which is more powerful as a method is
\function{degrees()}.

\begin{methoddesc}{degrees}{\optional{fullcircle}}
\var{fullcircle} is by default 360. This can cause the pen to have any
angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or
400 for gradians.
\end{methoddesc}