diff options
Diffstat (limited to 'Doc/library/turtle.rst')
| -rw-r--r-- | Doc/library/turtle.rst | 187 |
1 files changed, 183 insertions, 4 deletions
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 @@ Turtle state | :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 @@ Animation control 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 @@ Settings and special methods | :func:`window_height` | :func:`window_width` +Input methods + | :func:`textinput` + | :func:`numinput` + Methods specific to Screen | :func:`bye` | :func:`exitonclick` @@ -1157,6 +1166,26 @@ Appearance (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 @@ Appearance >>> 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 @@ Appearance 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 @@ Using screen events .. 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 @@ Using screen events >>> 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 @@ Using screen events >>> 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 @@ The demoscripts are: | | | 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 @@ The demoscripts are: | 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 @@ Changes since Python 2.6 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: |