deutsch     english    français     Print

Documentation Turtle Graphics

Module import: from gturtle import *

Sprites Library

Function Action
makeTurtle() defines all global commands and creates a (global) turtle in its down window
makeTurtle(color) same, but creates a turtle with given color
makeTurtle("sprites/turtle.gif") same, but creates a turtle with given sprite image
t = Turtle() creates a turtle object t
tf = TurtleFrame() creates a graphics windows where several turtles may live together
tf = TurtleFrame(title) same, but with given title
t = Turtle(tf) creates a turtle in the given TurtleFrame
clone() creates a turtle clone (same color, position, viewing direction)
isDisposed() returns True, if the window is closed
putSleep() pauses program execution until wakeUp() is called
wakeUp() resumes paused program execution
enableRepaint(False) disables automatic screen rendering
repaint() renders the screen manually (after disabling automatic rendering)
savePlayground() copies the playground into a internal image buffer (restore with clear())
savePlayground(fileName, format) copies the playground into a image file (format: "png" or "gif"). Returns True, if successful; otherwise False
setPlaygroundSize(width, height) sets the size of the turtle window independent of the option settings in TigerJython (must be called prior to makeTurtle())
setFramePosition(x, y) moves the upper left vertex of the turtle window to the given screen position
setFramePositionCenter() moves the turtle window to the screen center

Movements
back(distance), bk(distance) moves the turtle backwards for given distance (in turtle coordinates)
forward(distance), fd(distance) moves the turtle forwards for given distance (in turtle coordinates)
hideTurtle(), ht() hides the turtle (speeds-up the drawing, speed = -1)
home() puts the turtle in the center of the window with viewing direction to the north
left(angle), lt(angle) turns the turtle to the left (in degrees)
penDown(), pd() activates the pen (trace becomes visible)
penErase(), pe() sets the pen color to the background color
leftArc(radius, angle) moves the turtle on a left oriented arc with with given radius and sector angle (in degrees)
leftCircle(radius) moves the turtle on a left oriented circle with given radius (in turtle coordinates)
penUp(), pu() deactivates the pen (trace becomes invisible)
penWidth(width) selects the pen width (in pixels)
right(angle), rt(angle) turnes the turtle to the right (in degrees)
rightArc(radius, angle) moves the turtle on a right oriented arc with with given radius and sector angle (in degrees)
rightCircle(radius) moves the turtle on a right oriented circle with given radius (in turtle coordinates)
setCustomCursor(cursorImage) selects image file used as mouse cursor
setCustomCursor(cursorImage, Point(x, y)) selects image file use as mouse cursor and defines the hotspot relative to the picture
setLineWidth(width) sets the pen width (in pixels)
showTurtle(), st() shows the turtle
speed(speed) sets the speed of the turtle movement (1 to 1000, default 200) With speed (-1) the turtle moves the fastest (without animation)
delay(time) stops the program for the given amount of time (in milliseconds)
wrap() turtle positions outside the window are mapped inside the window (torus symmetry)
clip() turtles outside the window are invisible
getPlaygroundWidth() returns the horizontal size m of the turtle playground (turtle coordinates x = -m/2..m/2)
getPlaygroundHeight() eturns the vertical size n of the turtle playground (turtle coordinates y = -n/2..n/2)r

Positioning
direction(x, y) returns the angle to turn to the position (x, y) zurück
direction(coords) same, but coordinates given as list, tuple or complex
direction(turtle) returns the angle to turn to the position of another turtle
distance(x, y) returns the distance of the turtle to point(x, y)
distance(coords) same, but coordinates given as list, tuple or complex
distance(turtle) returns the distance to another turtle
getPos() returns the current position (list)
getX() returns the current x-coordinate
getY() returns the current y-coordinate
heading() returns the current viewing direction (in degrees, clockwise to the north)
heading(degrees) sets the viewing direction (in degrees, zero to the north, positive clockwise)
moveTo(x, y) moves the turtle to the given coordinates by drawing the trace
moveTo(coords) same, but coordinates given as list, tuple or complex
setHeading(degrees), setH(degrees) sets the viewing direction (in degrees, zero to the north, positive clockwise)
setRandomHeading() sets the viewing direction to a random value 0 ... 360°
setPos(x, y) moves the turtle to the given coordinates without drawing the trace
setPos(coords) same, but coordinates given as list, tuple or complex
setX(x) sets the turtle to given x-coordinate
setY(y) sets the turtle to given y-coordinate
setRandomPos(width, height) sets the turtle position to a random value in the given rectangle (center at current position)
setScreenPos(x, y) sets the turtle position to the given pixel coordinates
setScreenPos(Point(x, y)) sets the turtel position to the given point
towards(x, y) returns the direction (in degrees) to the given coordinates
towards(coords) same, but coordinates given as list, tuple or complex
towards(turtle) returns the direction to another turtle
toTurtlePos(x, y) returns a list of the turtle coordinates of the given pixel coordinates
toTurtlePos(Point(x, y)) returns a list of the turtle coordinates of the given point
pushState() saves the current turtle state on a stack (first-in-last-out)
popState() sets the turtle state to the last element of the stack and removes the state from the stack
clearStates() removes all elements from the state stack

Colors
askColor(title, defaultColor) opens a color selection dialog and returns the selected color (None if canceled)
clear() erases the traces and hides all turtles, but lets them where they are. If the image buffer created with savePlayground() is not empty, it is restored
clear(color) erases the traces, hides all turtles (lets them where they are) and paints the background with the given color
clean() erases the traces but lets the turtles where they are. The image buffer created with savePlayground() is erased
clean(color) erases the traces (but lets the turtles where they are) and paints the background with the color
clearScreen(), cs() erases the traces and sets the turtle to the home position
dot(diameter) paints a filled circle with given radius using the current pen color
openDot(diameter) paints a non-filled circle with given radius using the current pen color
spray(density, spread, size) paints a random point cloud at the turtle position with given number of points, spreading and point size (without size: size = 1)
fill() fills a closed area around the current turtlle position with the current fill color
fill(x , y) fills a closed area around the given position with the current fill color
fill(coords) same, but coordinates given as list, tuple or complex
fillToPoint() fills continuously from the current turtle position
fillToPoint(x , y) fills continuoiusly from the given point
fillToPoint(coords) same, but coordinates given as list, tuple or complex
fillToHorizontal( y) fills continuously die area between the horizontal line and the turtle position
fillToVertical(x) fills continuously die area between the veritcall line and the turtle position
fillOff() terminates the fill mode
getColor() returns the turtle color
getColorStr() returns the turtle color as X11 color string
getFillColor() returns the fill color
getFillColorStr() returns the fill color as X11 color string
getPixelColor() returns the color of the pixel (background or trace) at the current turtle position
(None, if outside turtle window)
getPixelColorStr() returns the color as X11 color string of the pixel at the current turtle position
(Empty, if X11 color name does not exist; None, if outside turtle window)
getRandomX11Color() returns a random X11 color string
makeColor(value) returns a color reference of given value. Value examples: ("7FFED4"), ("Aqua-Marine"), (0x7FFED4), (8388564), (0.5, 1.0, 0.83), (128, 255, 212), ("rainbow", n) with n = 0..1, light spectrum
makeColor(color, alpha) creates a transparent color for alpha between 0 and 1 (makeColor("red", 0.25) )
setColor(color) sets the turtle color
setPenColor(color) sets the turtle's pen color
setPenColor(color) sets the turtle's pen color
setPenWidth(width) sets the pen width (in pixels)
startPath() starts to register the turtle movement for a following fill operation
fillPath() closes the fill operation at current turtle position and fills the path with the current fill color
stampTurtle() creates an image of the turtle at the current position
stampTurtle(color) creates an image of the turtle with given color at current position

Callbacks
makeTurtle(mouseNNN = onMouseNNN)
use a comma separator to register more than one
registers the callback function onMouseNNN(x, y) that is called when a mouse event happens. Values for NNN: Pressed, Released, Clicked, Dragged, Moved, Entered, Exited, SingleClicked, DoubleClicked, Hit: Invocation in separate thread, HitX: same, but events are ignored until the previous callback returns
makeTurtle(turtleHit = onTurtleHit) registers the callback function onTurtleHit(x, y) that is called when the turtle image is clicked
t = Turtle(turtleHit = onTurtleHit) registers the callback function onTurtleHit(t, x, y) that is called when the image of turtle t is clicked
isLeftMouseButton(),
isRightMouseButton()
returns True, if the event is caused by the left/right mouse button
makeTurtle(keyNNN = onKeyNNN) registers the callback onKeyNNN(keyCode) that is called when a keyboard key is hit. Values for NNN: Pressed, Hit: Invocation in separate thread, HitX: same, but events are ignored until the previous callback returns. keyCode is a unique integer value that identifies the key
getKeyModifiers() returns an integer code for special keyboard keys (shift, ctrl, etc., also combined)
makeTurtle(closeClicked = onCloseClicked) registers the callback onCloseClicked() that is called when the title bar close button is hit. The window must be closed manually by calling dispose()
showSimulationBar(NNN = onNNN)

shows a dialog window with buttons 'Step', 'Run'/'Pause', 'Reset' and a slider to adjust the simulation period. The following callbacks can be registered: start, pause, step, reset, change(parameter: simulationPeriod), loop, exit (close button hit). loop is invoked in every simulation cycle by the simulation thread

showSimulationBar(ulx, uly, initPeriod, NNN = onNNN) same, but with dialog screen position (upper left corner) and simulation period (default: 100)
hideSimulationBar() closes the dialog and frees all resources

Text, Images and Sound
addStatusBar(20)   adds a status bar 20 pixels height
beep()   emits a short tone
playTone(freq) plays tone mit given frequency (in Hz) and duration 1000 ms (blocking function)
playTone(freq, block=False) same, but not-blocking function, used to play several tones at (about) the same time
playTone(freq, duration) plays tone with given frequency and given duration (in ms)
playTone([f1, f2, ...]) plays several tones in a sequence with given frequency and duration 1000 ms
playTone([(f1, d1), (f2, d2), ...]) plays serveral tones in a sequence with given frequency and given duration
playTone([("c", 700), ("e", 1500), ...]) plays serveral tones in a sequence with given (Helmholtz) pitch naming and duration.
Supported are: great octave, one-line to three-line octave (range C, C# up to h'''
playTone([("c", 700), ("e", 1500), ...], instrument = "piano") same, but selects instrument type. Supported are: piano, guitar, harp, trumpet, xylophone, organ, violin, panflute, bird, seashore, ... (see MIDI specifications)
playTone([("c", 700), ("e", 1500), ...], instrument = "piano", volume=10) same, but selects sound volume (0..100)
label(param) displays str(param) starting at the current turtle position (left adjusted)
label(param1, param2, ...) concatenates str(params) separated by spaces and displays the text
label(param1, param2, ..., adjust = 'x' same, but x = 'l' left adjusted (default), 'c' center adjusted, 'r' right adjusted
printerPlot(draw) prints the traces that are drawn in function draw
setFont(Font font) defines the font used by label(). font is an object of class Font,
ex: Font("Courier New", Font.BOLD, 12). Default: Font("SansSerif", Font.PLAIN, 24)
setFont(name) defines new font name using the current syte and size
setFont(name, style) defines new font name and style using the current size
style = Font.PLAIN, Font.BOLD, Font.ITALIC
setFont(name, style, size) defines new font name, style and size
setFontSize(size) defines new font size (style and size unchanged)
getTextHeight() returns the height of texts with current font (in pixels)
getTextAscent() returns the ascender height of texts with current font (in pixels)
getTextDescent() returns the descender height of texts with current font (in pixels)
getTextWidth(text) returns the width of given text with current font (in pixels)
setStatusText(text) shows the given text in the status bar. Any exiting text is erased
setTitle(title) shows the given title in the window title bar
img = getImage(path)

loads an image (in png, gif or jpp format) from the local file system or from an URL and returns an image reference. For path = sprites/nnn an image from the TigerJython distribution is loaded (see help/image-library for available images)

drawImage(img) draws the image img at the current turtle position with the current viewing direction
drawImage(path) loads an image (in png, gif or jpg format) from the local file system or from an URL and draws it at the current turtle position with the current viewing direction. For path = sprites/nnn an image from the TigerJython distribution is loaded


Video
rec = VideoRecorder(turtle, filename, resolution) creates a MP4 (H.264/AVC) video encoder, that captures the turtle playground (turtles, traces and images). filename is the output file (absolute or relative path). resolution must be a string with one of the supported video resolutions, e.g. "640x480". Use getSupportedResolutions() to enumerate all supported resolutions.
rec = VideoRecorder(turtleFrame, filename, resolution) same, using a TurtleFrame
rec = VideoRecorder(turtle, filename, resolution, ulx, uly) same, with given position of the playground's upper left corner with respect to the video image. Default values 0, 0
rec = VideoRecorder(turtleFrame, filename, resolution, ulx, uly) same, using a TurtleFrame
VideoRecorder.getSupportedResolutions() string enumeration of all supported video resolutions
rec.captureImage()

records one single image (frame). Calculation and capture of a single image can last any time. The resulting frame rate is determined by the chosen video resolution (normally 25 pictures/secs).

rec.captureImage(nb) same, but captures same picture nb times
rec.finish() terminates the recording and closes the output file


Dialogs    Documentation EntryDialog
msgDlg(message) opens a modal dialolg with an OK button and given message
msgDlg(message, title = title_text) same with title text
inputInt(prompt)

opens a modal dialog with OK/Cancel buttons. OK returns integer (the dialog is shown again, if no integer is entered). Cancel or Close terminate the program. The named parameter init sets an initialising value

inputInt(prompt, False)

same, but Cancel/Close do not terminate, but returns None

inputFloat(prompt) opens a modal dialog with OK/Cancel buttons. OK returns float (the dialog is shown again, if no float is entered). Cancel or Close terminate the program. The named parameter init sets an initialising value
inputFloat(prompt, False) same, but Cancel/Close do not terminate, but returns None
inputString(prompt) opens a modal dialog with OK/Cancel buttons. OK returns string. Cancel or Close terminate the program. The named parameter init sets an initialising value
inputString(prompt, False) same, but Cancel/Close do not terminate, but returns None
input(prompt) opens a modal dialog with OK/Cancel buttons. OK returns integer, float or string. Cancel or Close terminate the program. The named parameter init sets an initialising value
input(prompt, False) same, but Cancel/Close do not terminate, but returns None
askYesNo(prompt)

opens a modal dialog with Yes/No buttons. Yes returns True, No returns False. Cancel or Close terminate the program

askYesNo(prompt, False) same, but Close does not terminate, but returns None