--- turtle.rst Tue May 05 00:01:18 2009
+++ turtle31.rst Tue May 05 02:21:30 2009
@@ -144,9 +144,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`
@@ -182,9 +185,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`
@@ -195,6 +200,10 @@
    | :func:`turtles`
    | :func:`window_height`
    | :func:`window_width`
+   
+Input methods
+   | :func:`textinput`
+   | :func:`numinput`
 
 Methods specific to Screen
    | :func:`bye`
@@ -935,6 +944,24 @@
    >>> turtle.shapesize(outline=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.
+
+   >>> turtle.shape("circle")
+   >>> turtle.shapesize(5,2)
+   >>> turtle.shearfactor(0.5)
+   >>> turtle.shearfactor()
+   >>> 0.5
+
+
 .. function:: tilt(angle)
 
    :param angle: a number
@@ -968,16 +995,61 @@
    >>> turtle.fd(50)
 
 
-.. function:: tiltangle()
-
-   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).
+.. function:: tiltangle(angle=None)
+
+   :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
 
    >>> turtle.shape("circle")
    >>> turtle.shapesize(5,2)
    >>> turtle.tilt(45)
    >>> turtle.tiltangle()
    45
+
+
+.. 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.
+
+   >>> 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.
+
+   >>> turtle.shape("square")
+   >>> turtle.shapetransform(4, -1, 0, 2)
+   >>> turtle.get_shapepoly()
+  ((50, -20), (30, 20), (-50, 20), (-30, -20))
 
 
 Using events
@@ -1310,6 +1382,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")
@@ -1321,6 +1394,24 @@
    >>> def f():
    ...     fd(50)
    ...     lt(60)
+   ...
+   >>> screen.onkey(f, "Up")
+   >>> 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`.)
+
+
+   >>> def f():
+   ...     fd(50)
    ...
    >>> screen.onkey(f, "Up")
    >>> screen.listen()
@@ -1367,6 +1458,53 @@
                screen.ontimer(f, 250)
    >>> f()   ### makes the turtle marching around
    >>> 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
@@ -1843,6 +1981,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              |                       |
 +----------------+------------------------------+-----------------------+
@@ -1855,6 +1997,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)|                       |
 +----------------+------------------------------+-----------------------+
@@ -1888,3 +2034,29 @@
   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`.
+