summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libturtle.tex
blob: fa8f0dd4cd27cacaf16fa9d6f36ebe8523513b1e (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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
\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}{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.
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: 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}

\begin{funcdesc}{towards}{x, y}
Return the angle of the line from the turtle's position
to the point \var{x}, \var{y}. The co-ordinates may be
specified 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 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}{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 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
\function{degrees()}, which takes an optional argument letting 
you specify the number of units corresponding to a full circle:

\begin{methoddesc}[Turtle]{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}