#5923: update turtle module to version 1.1.
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 001f349..b3387b6 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -149,9 +149,12 @@
| :func:`shape`
| :func:`resizemode`
| :func:`shapesize` | :func:`turtlesize`
+ | :func:`shearfactor`
| :func:`settiltangle`
| :func:`tiltangle`
| :func:`tilt`
+ | :func:`shapetransform`
+ | :func:`get_shapepoly`
Using events
| :func:`onclick`
@@ -187,9 +190,11 @@
Using screen events
| :func:`listen`
- | :func:`onkey`
+ | :func:`onkey` | :func:`onkeyrelease`
+ | :func:`onkeypress`
| :func:`onclick` | :func:`onscreenclick`
| :func:`ontimer`
+ | :func:`mainloop`
Settings and special methods
| :func:`mode`
@@ -201,6 +206,10 @@
| :func:`window_height`
| :func:`window_width`
+Input methods
+ | :func:`textinput`
+ | :func:`numinput`
+
Methods specific to Screen
| :func:`bye`
| :func:`exitonclick`
@@ -1157,6 +1166,26 @@
(5, 5, 8)
+.. function:: shearfactor(self, shear=None):
+
+ :param shear: number (optional)
+
+ Set or return the current shearfactor. Shear the turtleshape according to
+ the given shearfactor shear, which is the tangent of the shear angle.
+ Do *not* change the turtle's heading (direction of movement).
+ If shear is not given: return the current shearfactor, i. e. the
+ tangent of the shear angle, by which lines parallel to the
+ heading of the turtle are sheared.
+
+ .. doctest::
+
+ >>> turtle.shape("circle")
+ >>> turtle.shapesize(5,2)
+ >>> turtle.shearfactor(0.5)
+ >>> turtle.shearfactor()
+ >>> 0.5
+
+
.. function:: tilt(angle)
:param angle: a number
@@ -1194,10 +1223,19 @@
>>> turtle.fd(50)
-.. function:: tiltangle()
+.. function:: tiltangle(angle=None)
- Return the current tilt-angle, i.e. the angle between the orientation of the
- turtleshape and the heading of the turtle (its direction of movement).
+ :param angle: a number (optional)
+
+ Set or return the current tilt-angle. If angle is given, rotate the
+ turtleshape to point in the direction specified by angle,
+ regardless of its current tilt-angle. Do *not* change the turtle's
+ heading (direction of movement).
+ If angle is not given: return the current tilt-angle, i. e. the angle
+ between the orientation of the turtleshape and the heading of the
+ turtle (its direction of movement).
+
+ Deprecated since Python 3.1
.. doctest::
@@ -1209,6 +1247,46 @@
45.0
+.. function:: shapetransform(t11=None, t12=None, t21=None, t22=None)
+
+ :param t11: a number (optional)
+ :param t12: a number (optional)
+ :param t21: a number (optional)
+ :param t12: a number (optional)
+
+ Set or return the current transformation matrix of the turtle shape.
+
+ If none of the matrix elements are given, return the transformation
+ matrix as a tuple of 4 elements.
+ Otherwise set the given elements and transform the turtleshape
+ according to the matrix consisting of first row t11, t12 and
+ second row t21, 22. The determinant t11 * t22 - t12 * t21 must not be
+ zero, otherwise an error is raised.
+ Modify stretchfactor, shearfactor and tiltangle according to the
+ given matrix.
+
+ .. doctest::
+
+ >>> turtle.shape("square")
+ >>> turtle.shapesize(4,2)
+ >>> turtle.shearfactor(-0.5)
+ >>> turtle.shapetransform()
+ >>> (4.0, -1.0, -0.0, 2.0)
+
+
+.. function:: get_shapepoly():
+
+ Return the current shape polygon as tuple of coordinate pairs. This
+ can be used to define a new shape or components of a compound shape.
+
+ .. doctest::
+
+ >>> turtle.shape("square")
+ >>> turtle.shapetransform(4, -1, 0, 2)
+ >>> turtle.get_shapepoly()
+ ((50, -20), (30, 20), (-50, 20), (-30, -20))
+
+
Using events
------------
@@ -1595,6 +1673,7 @@
.. function:: onkey(fun, key)
+ onkeyrelease(fun, key)
:param fun: a function with no arguments or ``None``
:param key: a string: key (e.g. "a") or key-symbol (e.g. "space")
@@ -1613,6 +1692,25 @@
>>> screen.listen()
+.. function:: onkeypress(fun, key=None):
+
+ :param fun: a function with no arguments or ``None``
+ :param key: a string: key (e.g. "a") or key-symbol (e.g. "space")
+
+ Bind *fun* to key-press event of key if key is given,
+ or to any key-press-event if no key is given.
+ Remark: in order to be able to register key-events, TurtleScreen
+ must have focus. (See method :func:`listen`.)
+
+ .. doctest::
+
+ >>> def f():
+ ... fd(50)
+ ...
+ >>> screen.onkey(f, "Up")
+ >>> screen.listen()
+
+
.. function:: onclick(fun, btn=1, add=None)
onscreenclick(fun, btn=1, add=None)
@@ -1659,6 +1757,53 @@
>>> running = False
+.. function:: mainloop()
+
+ Starts event loop - calling Tkinter's mainloop function.
+ Must be the last statement in a turtle graphics program.
+ Must *not* be used if a script is run from within IDLE in -n mode
+ (No subprocess) - for interactive use of turtle graphics. ::
+
+ >>> screen.mainloop()
+
+
+Input methods
+-------------
+
+.. function:: textinput(title, prompt)
+
+ :param title: string
+ :param prompt: string
+
+ Pop up a dialog window for input of a string. Parameter title is
+ the title of the dialog window, propmt is a text mostly describing
+ what information to input.
+ Return the string input. If the dialog is canceled, return None. ::
+
+ >>> screen.textinput("NIM", "Name of first player:")
+
+
+.. function:: numinput(self, title, prompt,
+ default=None, minval=None, maxval=None):
+
+ :param title: string
+ :param prompt: string
+ :param default: number (optional)
+ :param prompt: number (optional)
+ :param prompt: number (optional)
+
+ Pop up a dialog window for input of a number. title is the title of the
+ dialog window, prompt is a text mostly describing what numerical information
+ to input. default: default value, minval: minimum value for imput,
+ maxval: maximum value for input
+ The number input must be in the range minval .. maxval if these are
+ given. If not, a hint is issued and the dialog remains open for
+ correction.
+ Return the number input. If the dialog is canceled, return None. ::
+
+ >>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)
+
+
Settings and special methods
----------------------------
@@ -2159,6 +2304,10 @@
| | | as Hanoi discs |
| | | (shape, shapesize) |
+----------------+------------------------------+-----------------------+
+| nim | play the classical nim game | turtles as nimsticks, |
+| | with three heaps of sticks | event driven (mouse, |
+| | against the computer. | keyboard) |
++----------------+------------------------------+-----------------------+
| paint | super minimalistic | :func:`onclick` |
| | drawing program | |
+----------------+------------------------------+-----------------------+
@@ -2171,6 +2320,10 @@
| planet_and_moon| simulation of | compound shapes, |
| | gravitational system | :class:`Vec2D` |
+----------------+------------------------------+-----------------------+
+| round_dance | dancing turtles rotating | compound shapes, clone|
+| | pairwise in opposite | shapesize, tilt, |
+| | direction | get_polyshape, update |
++----------------+------------------------------+-----------------------+
| tree | a (graphical) breadth | :func:`clone` |
| | first tree (using generators)| |
+----------------+------------------------------+-----------------------+
@@ -2204,6 +2357,32 @@
This behaviour corresponds to a ``fill()`` call without arguments in
Python 2.6.
+Changes since Python 3.0
+========================
+
+- The methods :meth:`Turtle.shearfactor`, :meth:`Turtle.shapetransform` and
+ :meth:`Turtle.get_shapepoly` have been added. Thus the full range of
+ regular linear transforms is now available for transforming turtle shapes.
+ :meth:`Turtle.tiltangle` has been enhanced in functionality: it now can
+ be used to get or set the tiltangle. :meth:`Turtle.settiltangle` has been
+ deprecated.
+
+- The method :meth:`Screen.onkeypress` has been added as a complement to
+ :meth:`Screen.onkey` which in fact binds actions to the keyrelease event.
+ Accordingly the latter has got an alias: :meth:`Screen.onkeyrelease`.
+
+- The method :meth:`Screen.mainloop` has been added. So when working only
+ with Screen and Turtle objects one must not additonally import
+ :func:`mainloop` anymore.
+
+- Two input methods has been added :meth:`Screen.textinput` and
+ :meth:`Screen.numinput`. These popup input dialogs and return
+ strings and numbers respectively.
+
+- Two example scripts :file:`tdemo_nim.py` and :file:`tdemo_round_dance.py`
+ have been added to the Demo directory (source distribution only). As usual
+ they can be viewed and executed within the demo viewer :file:`turtleDemo.py`.
+
.. doctest::
:hide: