DOCUMENTATION for xturtle.py , Version 0.95a0 PRELIMINARY REMARK: ===> New and changed features since xturtle 0.91 <=== ===> are marked in the OVERVIEW section <=== The class Turtle ================ Alias: Pen ... implements a traditional turtle to do turtle graphics. It inherits from several Parent classes: class Turtle(RawTurtle) Method resolution order: Turtle RawTurtle TPen TNavigator __builtin__.object Moreover it has a TurtleScreen-object as attribute, quasi the canvas it draws on. Some of TurtleScreen's methods appear also as 'screen-oriented' methods of RawTurtle. NB! Those will be marked as SCREEN ORIENTED below. That means, they act on the TurtleScreen object and affect all turtles (Turtle- od Pen-objects) equally on that screen. For example: mypen.colormode(255) will set colormode to 255 not only for mypen but for all turtles on that TurtleScreen (as would do yourpen.colormode(255).) So, to do turtle graphics we only need to use Turtle objects or RawTurtle objects. A short note on the relation between RawTurtle and Turtle: RawTurtle implements 'turtles' on a canvas (optionally a ScrolledCanvas), which has to be passed as an argument to the RawTurtle constuctor. Turtle inherits all methods of RawTurtle, but drawing takes place on a (scrolled) canvas, which will be automatically generated, whenever a Turtle method is called for the first time. Moreover all of it's methods exist additionally as functions - in fact (behind the scene) as method calls for some anonymous (unknown, invisible, unnamed) turtle. In the following RawTurtle's methods (and two additional methods of Turtle) are documented in functional groups as e.g. turtle movement, pen control etc. ====================================================== Methods of class RawTurtle (and Turtle), ====================================================== Those methods appear in the module xturtle also as functions. In this documentation the argumentlist for functions is given. --->> Methods have the additional first argument self <<--- --->> which is omitted here. <<--- ------------------------------------------------------ OVERVIEW over available Turtle methods: I. TURTLE MOTION ----------------- I.a MOVE AND DRAW forward, fd back, bk, back right, rt left, lt goto, setpos, setposition setx sety setheading, seth home circle dot stamp (NEW!) clearstamp (NEW!) clearstamps (NEW!) undo (NEW!) I.b TELL PEN'S STATE position, pos towards xcor ycor heading distance I.c SETTING AND MEASUREMENT degrees radians mode reset_odometer (NEW!) odometer_on (NEW!) odometer_off (NEW!) get_odometer (NEW!) II. PEN CONTROL --------------- II.a DRAWING STATE pendown, pd, down penup, pu, up pensize, width pen isdown, pendownp (NEW!) II.b COLOR CONTROL color pencolor fillcolor colormode screen oriented II.c FILLING fill begin_fill end_fill II.c MORE DRAWING CONTROL reset clear write III. TURTLE STATE ----------------- III.a VISIBILITY showturtle, st hideturtle, ht isvisible, shownp (NEW!) III.b APPEARANCE shape addshape screen oriented resizemode turtlesize (CHANGED!) tilt (NEW!) settilt (NEW!) getshapes screen oriented start_poly end_poly get_poly IV. ANIMATION CONTROL --------------------- speed tracer delay screen oriented update V. USING EVENTS --------------- onclick (NEW!) onrelease (NEW!) ondrag (NEW!) onscreenclick (CHANGED!) screen oriented onkey screen oriented ontimer screen oriented listen screen oriented VI. SPECIAL PEN METHODS ----------------------- clone getturtle getturtles VII. WINDOW CONTROL ------------------- bgcolor screen oriented bgpic screen oriented clearscreen, resetscreen screen oriented screensize screen oriented screen_height screen oriented screen_width screen oriented window_width screen oriented window_height screen oriented getcanvas Screen oriented getscreen Screen oriented bye Turtle method! winsize Turtle method! setup Turtle method! VIII. Additional features (NEW!) ------------------------- xturtle.cfg for storing start configuration utilities for creating and using docstrings in other languages (I) TURTLE MOTION: ================== (a) --- MOVE (AND DRAW) forward(distance) fd(distance) Move the turtle forward by the specified distance, in the direction the turtle is headed. --- Argument: a number (integer or float) call: forward() --or: fd() Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 0.00) >>> turtle.forward(25) >>> turtle.position() (25.00,0.00) >>> turtle.forward(-75) >>> turtle.position() (-50.00,0.00) back(distance) bk(distance) backward(distance) Move the turtle backward by distance, opposite to the direction the turtle is headed The turtle's heading does not change. --- Argument: a number (integer or float) call: back() --or: bk() --or: backward() Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 0.00) >>> turtle.backward(30) >>> turtle.position() (-30.00, 0.00) right(angle) rt(angle) Turn turtle right angle units (units are by default degrees, but can be set via the degrees() and radians() functions.) --- Argument: a number (integer or float) call: right() --or: rt() Example (for a Turtle instance named turtle): >>> turtle.heading() 22.0 >>> turtle.right(45) >>> turtle.heading() 337.0 left(angle) lt(angle) Turn turtle left angle units (units are by default degrees, but can be set via the degrees() and radians() functions.) --- Argument: a number (integer or float) call: left() --or: lt() Example (for a Turtle instance named turtle): >>> turtle.heading() 22.0 >>> turtle.left(45) >>> turtle.heading() 67.0 goto(pos, y=None) setpos(pos, y=None) setposition(pos, y=None) Move turtle to an absolute position. If the pen is down, then a line will be drawn. The turtle's orientation does not change. --- Arguments: two numbers (then pos is an x-coordinate) or pos is a pair/vector of numbers (and y is None) call: goto(,) # two coordinates --or: goto((,)) # a pair (tuple) of coordinates --or: goto(<2-vector>) # e.g. as returned by pos() >>> tp = turtle.pos() >>> tp (0.00, 0.00) >>> turtle.setpos(60,30) >>> turtle.pos() (60.00,30.00) >>> turtle.setpos((20,80)) >>> turtle.pos() (20.00,80.00) >>> turtle.setpos(tp) >>> turtle.pos() (0.00,0.00) setx(x) Set the turtle's first coordinate to x Second coordinate remains unchanged. --- Argument: a number (integer or float) call: setx() Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 240.00) >>> turtle.setx(10) >>> turtle.position() (10.00, 240.00) sety(y) Sets the turtle's second coordinate to y First coordinate remains unchanged. --- Argument: a number (integer or float) call: sety() Example (for a Turtle instance named turtle): >>> turtle.position() (0.00, 40.00) >>> turtle.sety(-10) >>> turtle.position() (0.00, -10.00) setheading(to_angle) seth(to_angle) Set the turtle facing the given angle. Here are some common directions in degrees: --- standard - mode: logo-mode: -------------------|-------------------- 0 - east 0 - north 90 - north 90 - east 180 - west 180 - south 270 - south 270 - west --- Argument: a number (integer or float) call: setheading() Example (for a Turtle instance named turtle): >>> turtle.setheading(90) >>> turtle.heading() 90 home(): Move turtle to the origin - coordinates (0,0) --- No arguments. Example (for a Turtle instance named turtle): >>> turtle.home() circle(radius, extent=None, steps=None) Draw a circle with given radius. The center is radius units left of the turtle; extent - an angle - determines which part of the circle is drawn. If not given, the entire circle is drawn. - If 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 radius is positive, otherwise in a clockwise direction. In the process, the direction of the turtle is changed by the amount of the extent. - As the circle is approximated by an inscribed regular polygon, steps determines the number of steps to use. If not given, it will be calculated automatically. --- Arguments: number, Optional arguments: number, integer call: circle() # full circle --or: circle(, ) # arc --or: circle(, , ) Example (for a Turtle instance named turtle): >>> turtle.circle(50) >>> turtle.circle(120, 180) # semicircle dot(size=None, *color) Draw a dot with diameter size, using pencolor. If size is not given, pensize()+4 is used. Argument: size is number >= 1 (if given) color is colorstring or numeric color tuple Example (for a Turtle instance named turtle): >>> turtle.dot() >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50) stamp(self): Stamps a copy of the turtle shape onto the canvas at the current turtle position. Returns an id for that stamp, which can be used to delete it by calling clearstamp(stamp_id). Example (for a Turtle instance named turtle): >>> turtle.color("blue") >>> turtle.stamp() 13 >>> turtle.fd(50) clearstamp(self, stampid): Delete stamp with given stampid Argument: stampid : return value of previous stamp() call Example (for a Turtle instance named turtle): >>> turtle.color("blue") >>> turtle.s = stamp() >>> turtle.fd(50) >>> turtle.clearstamp() clearstamps(self, n=None): If n is None, delete all of pen's stamps, else (n>0) delete first n stamps or (n<0) last n stamps. Optional argument: n : integer Example (for a Turtle instance named turtle): >>> for i in range(8): turtle.stamp(); turtle.fd(30) ... >>> turtle.clearstamps(2) >>> turtle.clearstamps(-2) >>> turtle.clearstamps() undo(self): undo (repeatedly) the last turtle action. The number of available undo actions is determined by size of the undobuffer. Example (for a Turtle instance named turtle): >>> for i in range(4): turtle.fd(50); turtle.lt(80) >>> for i in range(8): turtle.undo() (b) --- TELL PEN'S STATE ======================== position() pos() Return the turtle's current location (x,y) (as a vector) No arguments. Example (for a Turtle instance named turtle): >>> turtle.pos() (0.00, 240.00) towards(pos, y=None) Return the angle, between the line from turtle-position to pos and the turtle's start orientation. (Depends on modes - "standard" or "logo") --- Arguments: two numbers (then pos is an x-coordinate) or pos is a pair/vector of numbers (and y is None) or pos is a Turtle instance (and y is None) call: towards(,) # two coordinates --or: towards((,)) # a pair (tuple) of coordinates --or: towards(<2-vector>) # e.g. as returned by pos() --or: towards(mypen) # where mypen is another turtle Example (for a Turtle instance named turtle): >>> turtle.pos() (10.00, 10.00) >>> turtle.towards(0,0) 225.0 xcor() Return the turtle's x coordinate No arguments. Example (for a Turtle instance named turtle): >>> reset() >>> turtle.left(60) >>> turtle.forward(100) >>> print turtle.xcor() 50.0 ycor() Return the turtle's y coordinate No arguments. Example (for a Turtle instance named turtle): >>> reset() >>> turtle.left(60) >>> turtle.forward(100) >>> print turtle.ycor() 86.6025403784 heading() Return the turtle's current heading. No arguments. Example (for a Turtle instance named turtle): >>> turtle.left(67) >>> turtle.heading() 67.0 distance(pos, y=None) Return the distance from the turtle to pos, in turtle step units. --- Arguments: two numbers (then pos is an x-coordinate) or pos is a pair/vector of numbers (and y is None) or pos is a Turtle instance (and y is None) call: distance(,) # two coordinates --or: distance((,)) # a pair (tuple) of coordinates --or: distance(<2-vector>) # e.g. as returned by pos() --or: distance(mypen) # where mypen is another turtle Example (for a Turtle instance named turtle): >>> turtle.pos() (0.00, 0.00) >>> turtle.distance(30,40) 50.0 >>> pen = Turtle() >>> pen.forward(77) >>> turtle.distance(pen) 77.0 (c) --- SETTINGS FOR MEASUREMENT degrees(fullcircle=360.0) Set angle measurement units to degrees. Optional argument: fullcircle: number (set number of 'degrees' for a full circle). call: degrees() # fullcircle defaults to 360 - # learn more with help(degrees) Example (for a Turtle instance named turtle): >>> turtle.left(90) >>> turtle.heading() 90 >>> turtle.degrees(400.0) # angle measurement in gon >>> turtle.heading() 100 >>> turtle.degrees() >>> turtle.heading() 90 radians() Set the angle measurement units to radians. No arguments. Example (for a Turtle instance named turtle): >>> turtle.heading() 90 >>> turtle.radians() >>> turtle.heading() 1.5707963267948966 mode(mode=None) Sets turtle-mode to 'standard' or 'logo' and resets turtle. Mode 'standard' is compatible with turtle.py. Mode 'logo' is compatible with most Logo-Turtle-Graphics'. If mode is not given, return the current mode. call: mode('standard') --or: mode('logo') --or: mode() Mode Initial turtle heading positive angles ------------|-------------------------|------------------- 'standard' to the right (east) counterclockwise 'logo' upward (north) clockwise Examples: >>> mode('logo') # resets turtle heading to north >>> mode() 'logo' reset_odometer(): Reset the turtle odometer to 0.0 odometer_on(): Resume the turtle odometer, i. e. the distance the turtle moves will be recorded. odometer_off(): Suspend the turtle odometer. get_odometer(): Return the turtle odometer value (II) PEN CONTROL: ================= (a) --- DRAWING STATE pendown() pd() down() Pull the pen down -- no drawing when moving. Aliases: pendown, pd, down No argument Example (for a Turtle instance named turtle): >>> turtle.pendown() penup() pu() up() Pull the pen up -- no drawing when moving. No argument Example: >>> turtle.penup() pensize(width=None) width(width=None) Set (or return) the line thickness to width. If resizemode is set to "auto" and turtleshape is a polygon, that polygon is drawn with the same line thickness. IF argument --- Argument: positive number call: pensize() Example (for a Turtle instance named turtle): >>> turtle.pensize() 1 turtle.pensize(10) # from here on lines of width 10 are drawn pen(pen=None, **pendict) return (with no argument) or set the pen's attributes, in a 'pen-dictionary' with the following key/value pairs: "shown" : True/False "pendown" : True/False "pencolor" : color-string or color-tuple "fillcolor" : color-string or color-tuple "pensize" : positive number "speed" : number in range 0..10 "resizemode" : "auto" or "user" or "noresize" "stretchfactor": positive number "outline" : positive number This dicionary can be used as argument for a subsequent pen()-call to restore the former pen-state. Moreover one or more of these attributes can be provided as keyword-arguments. This can be used to set several pen attributes in one statement. Arguments: pen : a dictionary with some or all of the above listed keys. **pendict : one or more keyword-arguments with the above listed keys as keywords. Examples (for a Turtle instance named turtle): >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10) >>> turtle.pen() {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1, 'pencolor': 'red', 'pendown': True, 'fillcolor': 'black', 'stretchfactor': 1, 'speed': 3} >>> penstate=turtle.pen() >>> turtle.color("yellow","") >>> turtle.penup() >>> turtle.pen() {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1, 'pencolor': 'yellow', 'pendown': False, 'fillcolor': '', 'stretchfactor': 1, 'speed': 3} >>> p.pen(penstate, fillcolor="green") >>> p.pen() {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1, 'pencolor': 'red', 'pendown': True, 'fillcolor': 'green', 'stretchfactor': 1, 'speed': 3} isdown(self): """Return True if pen is down, False if it's up. Aliases: isdown | pendownp --- No argument. Example (for a Turtle instance named turtle): >>> turtle.penup() >>> turtle.isdown() False >>> turtle.pendown() >>> turtle.isdown() True (b) --- COLOR CONTROL color(*args) Return or set the pencolor and fillcolor. If turtleshape is a polygon, outline and interior of that polygon is drawn with the newly set colors. - Arguments: Several input formats are allowed. They use 0, 1, 2, 3, or 6 arguments as follows: - color() return the current pencolor and the current fillcolor as a pair of color specification strings as are returned by pencolor and fillcolor. - color(s), color((r,g,b)), color(r,g,b) inputs as in pencolor, set both, fillcolor and pencolor, to the given value. - color(s1, s2), color((r1,g1,b1), (r2,g2,b2)) color(r1, g1, b1, r2, g2, b2) equivalent to pencolor(s1) fillcolor(s2) and analog, if the other input formats are used. call: color() --or: color(, ) --or with s in range 0 .. colormode (i.e. 1.0 or 255) - color((, , )) - color((, , ), (, , )) - color((, , , , , )) - color() Example (for a Turtle instance named turtle): >>> turtle.color('red', 'green') >>> turtle.color() ('red', 'green') >>> colormode(255) >>> color(40, 80, 120, 160, 200, 240) >>> color() ('#285078', '#a0c8f0') pencolor(*args) Return or set the pen color. If turtleshape is a polygon, the outline of that polygon is drawn with the newly set pencolor. -Arguments: Four input formats are allowed: - pencolor() return the current pencolor as color specification string, possibly in hex-number format (see example). May be used as input to another color/pencolor/fillcolor call. - pencolor(s) s is a Tk specification string, such as "red" or "yellow" - pencolor((r, g, b)) *a tuple* of r, g, and b, which represent, an RGB color, and each of r, g, and b are in the range 0..colormode, where colormode is either 1.0 or 255 - pencolor(r, g, b) r, g, and b represent an RGB color, and each of r, g, and b are in the range 0..colormode call: pencolor() --or with s in range 0 .. colormode (i.e. 1.0 or 255) - pencolor(, , ) - pencolor((, , )) - pencolor() Example (for a Turtle instance named turtle): >>> turtle.pencolor('brown') >>> tup = (0.2, 0.8, 0.55) >>> turtle.pencolor(tup) >>> turtle.pencolor() '#33cc8c' fillcolor(*args) Return or set the fill color. If turtleshape is a polygon, that polygon is filled with the newly set fillcolor. Four input formats are allowed: - fillcolor() return the current pencolor as color specification string, possibly in hex-number format (see example). May be used as input to another color/pencolor/fillcolor call. - fillcolor(s) s is a Tk specification string, such as "red" or "yellow" - fillcolor((r, g, b)) *a tuple* of r, g, and b, which represent, an RGB color, and each of r, g, and b are in the range 0..colormode, where colormode is either 1.0 or 255 - fillcolor(r, g, b) r, g, and b represent an RGB color, and each of r, g, and b are in the range 0..colormode call: fillcolor() --or with s in range 0 .. colormode (i.e. 1.0 or 255) - fillcolor(, , ) - fillcolor((, , )) - fillcolor() Example (for a Turtle instance named turtle): >>> turtle.fillcolor('violet') >>> tup = turtle.pencolor() >>> turtle.fillcolor(tup) >>> turtle.fillcolor(0, .5, 0) colormode(cmode=None) Return the colormode or set it to 1.0 or 255. --- Argument: None or one of the values 1.0 or 255 call: colormode(255) # for example --or: colormode() --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.colormode(255) >>> turtle.pencolor(240,160,80) (c) --- FILLING fill(flag) Call fill(True) before drawing the shape you want to fill, and fill(False) when done. Argument: True/False (or 1/0 respectively) Example (for a Turtle instance named turtle): >>> turtle.fill(True) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.fill(False) begin_fill() Called just before drawing a shape to be filled. No argument. Example (for a Turtle instance named turtle): >>> turtle.begin_fill() >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.end_fill() end_fill() Fill the shape drawn after the call begin_fill(). No argument. Example (for a Turtle instance named turtle): >>> turtle.begin_fill() >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.left(90) >>> turtle.forward(100) >>> turtle.end_fill() (d) --- MORE DRAWING CONTROL reset() Delete the pen's drawing from the screen, re-center the pen and set variables to the default values. Example (for a Turtle instance named turtle): >>> turtle.position() (0.00,-22.00) >>> turtle.seth(100) >>> turtle.position() (0.00,-22.00) >>> turtle.heading() 100.0 >>> turtle.reset() >>> turtle.position() (0.00,0.00) >>> turtle.heading() 0.0 clear(n=None) Delete the pen's drawings from the screen. The pen does not move. Drawings of other pens are not affected. Examples (for a Turtle instance named turtle): >>> turtle.clear() NB! Optional argument n is experimental NB! and will be documented or removed later. write(arg, move=False, align='left', font=('Arial', 8, 'normal')) Write text at the current pen position according to align ("left", "center" or right") and with the given font. If move is true, the pen is moved to the bottom-right corner of the text. By default, move is False. Example (for a Turtle instance named turtle): >>> turtle.write('The race is on!') >>> turtle.write('Home = (0, 0)', True, align="center") (III) Turtle State: =================== (a) --- VISIBILITY showturtle() st() Makes the turtle visible. No argument. Example (for a Turtle instance named turtle): >>> turtle.hideturtle() >>> turtle.showturtle() hideturtle() ht() Makes the turtle invisible. It's a good idea to do this while you're in the middle of a complicated drawing, because hiding the turtle speeds up the drawing observably. No argument. Example (for a Turtle instance named turtle): >>> turtle.hideturtle() isvisible(self): Return True if the Turtle is shown, False if it's hidden. Aliases: isvisible | shownp --- No argument. Example (for a Turtle instance named turtle): >>> turtle.hideturtle() >>> if not turtle.isvisible(): print "Turtle is hidden!" Turtle is hidden! (b) --- APPEARANCE shape(name=None) Set pen shape to shape with given name. Shape must exist in the TurtleScreen's shape dictionary. Initially there are three polygon shapes: 'arrow', 'turtle', 'circle'. Without argument return name of current shape. Example (for a Turtle instance named turtle): >>> turtle.shape() 'arrow' >>> turtle.shape("turtle") >>> shape() 'turtle' addshape(name, shape=None) Adds a turtle shape to TurtleScreen's shape dictionary. Arguments: (1) name is the name of a gif-file and shape is None. Installs the corresponding image shape. (2) name is an arbitrary string and shape is a tuple of pairs of coordinates. Installs the corresponding polygon shape (3) name is an arbitrary string and shape is a (compound) Shape object. Installs the corresponding compound shape. --- THIS IS A SCREEN ORIENTED METHOD --- To use a shape, you have to issue the command shape(shapename). Examples (for a Turtle instance named turtle): >>> turtle.addshape("triangle", ((5,-3),(0,5),(-5,-3))) resizemode(rmode=None) Set resizemode to one of the values: "auto", "user", "noresize". Different resizemodes have the following effects: - "auto" adapts the appearance of the turtle corresponding to the value of pensize. - "user" adapts the appearance of the turtle according to the values of stretchfactor and outlinewidth (outline), which are set by turtlesize() - "noresize" no adaption of the turtle's appearance takes place. If no argument is given, return current resizemode. --- (Optional) Argument: one of the strings "auto", "user", "noresize" call: resizemode("user") # for example --or: resizemode() Examples: >>> resizemode("noresize") >>> resizemode() 'noresize' turtlesize(self, stretchx=None, stretchy=None, outline=None): Return or set the pen's attributes x/y-stretchfactors and/or outline. Sets resizemode to "user". If and only if resizemode is set to "user", the turtle will be displayed stretchfactor times as big as the original shape with an outline of width outline. Optinonal arguments: stretchx : positive number stretchy : positive number outline : positive number Examples (for a Turtle instance named turtle): >>> turtle.resizemode("user") >>> turtlesize(5, 5, 12) >>> turtlesize(outline=8) tilt(self, angle): Turns the shape of the turtle by angle clockwise with respect to it's current tilt-angle. Does not affect it's orientation, i. e. it's direction of movement. Argument: angle : number Examples (for a Turtle instance named turtle): >>> turtle.shape("circle") >>> turtle.turtlesize(5,2) >>> turtle.tilt(30) >>> turtle.fd(50) >>> turtle.tilt(30) >>> turtle.fd(50) settilt(self, angle=None): Turns the shape of the turtle to angle with respect to it's current orientation, but does not affect it's orientation, i. e. it's direction of movement. If no argument is given, the current tilt-angle is returned. Optional argument: angle : number Examples (for a Turtle instance named turtle): >>> turtle.shape("circle") >>> turtle.turtlesize(5,2) >>> turtle.tilt(45) >>> turtle.fd(50) >>> turtle.tilt(-45) >>> turtle.fd(50) getshapes() Return a list of names of all currently available shapes. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.getshapes() ['arrow', 'blank', 'circle', 'turtle'] start_poly() Start recording the vertices of a polygon. Current turtle position is first point of polygon. Example (for a Turtle instance named turtle): >>> turtle.start_start() end_poly() Stop recording the vertices of a polygon. Current turtle position is first last point of polygon. This will be connected with the first point. Example (for a Turtle instance named turtle): >>> turtle.end_poly() get_poly() Return the lastly recorded polygon. Example (for a Turtle instance named turtle): >>> p = turtle.getpoly() >>> turtle.addshape("myFavouriteShape", p) ------->>>>> EXCURSUS about COMPOUND SHAPES To use compound turtle shapes, which consist of several polygons of different color, you must use the helper class Shape explicitely as described below: class Shape(object) | Data structure modeling shapes. | | attribute _type is one of "polygon", "image", "compound" | attribute _data is - depending on _type a poygon-tuple, | an image or a list constructed using the addComponent method. | | Methods defined here: | | __init__(self, type, data=None) | | addComponent(self, poly, fill, outline=None) | add component to a shape of type compound. | --- | Arguments: poly is a polygon, i. e. a tuple of number pairs. | fill is the fillcolor of the component, | outline is the outline color of the component. | | call (for a Shapeobject namend s): | -- s.addcomponent(((0,0), (10,10), (-10,10)), "red", "blue") | | Example: | >>> poly = ((0,0),(10,-5),(0,10),(-10,-5)) | >>> s = Shape("compound") | >>> s.addComponent(poly, "red", "blue") | ### .. add more components and then use addshape() | | A shape constructed like this can finally be added to | the TurtleScreen's shapelist using the addshape method | as shown above | | PLEASE NOTE: addComponent() is a method of class Shape (not of | Turtle) and thus there is NO FUNCTION of the same name. | ---------------------------------- END OF EXCURSUS <<<<<----- (IV) ANIMATION CONTROL ====================== speed(speed=None) Return the turtle's speed or set it to an integer value in the range 0 .. 10. If no argument is given: current speed is returned. If input is a number greater than 10 or smaller than 0.5, speed is set to 0. Speedstrings correspond to speedvalues in the following way: 'fastest' : 0 'fast' : 10 'normal' : 6 'slow' : 3 'slowest' : 1 speeds from 1 to 10 enforces increasingly faster animation of line drawing and turtle turning. !!! speed = 0 : *no* animation takes place. forward/back makes turtle jump and likewise left/right make the turtle turn instantly Optional Argument: number or one of the strings 'fastest', 'fast', 'normal', 'slow', 'slowest' (for compatibility with turtle.py) !!! Optional Argument: number in range 0..10, or 'speedstring' as described above. call: speed(1) # slow --or: speed(10) # fastest --or: speed('fastest') --or: speed(0) Example (for a Turtle instance named turtle): >>> turtle.speed(3) tracer(flag=None, delay=None) tracer(True/False) turns turtle animation on/off. tracer accepts positive integers as first argument: tracer(n) has the effect, that only each n-th update is really performed. Can be used to accelerate the drawing of complex graphics.) Second arguments sets delay value (see RawTurtle.delay()) Example (for a Turtle instance named turtle): >>> turtle.tracer(8, 25) >>> l=2 >>> for i in range(200): turtle.fd(l) turtle.rt(90) l+=2 delay(delay=None) Return or set the drawing delay in milliseconds. Screen oriented method, i.e. affects all Turtles on the Screen. Argument: None or number >= 0. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.delay(15) >>> turtle.delay() 15 update() Perform a TurtleScreen update. Especially useful to control screen updates when tracer(False) is set. Example (for a Turtle instance named turtle): >>> tracer(0) >>> for i in range(36): for j in range(5): turtle.fd(100) turtle.lt(72) turtle.update() # draws a pentagon at once turtle.lt(10) (V) USING EVENTS: ================= onclick(self, fun, btn=1, add=None): Bind fun to mouse-click event on this turtle on canvas. Arguments: fun must be a function with two arguments, the coordinates of the clicked point on the canvas. num, the number of the mouse-button defaults to 1 Example (for a Turtle instance named turtle): >>> class MyTurtle(Turtle): def glow(self,x,y): self.fillcolor("red") >>> t = MyTurtle() >>> t.onclick(t.glow) ### Subsequently clickinfg into the turtle will turn it'S ### fillcolor red. >>> turtle.onclick(None) ###event-binding will be removed onrelease(self, fun, btn=1, add=None): Bind fun to mouse-button-release event on canvas. Arguments: fun must be a function with two arguments, the coordinates of the clicked point on the canvas. num, the number of the mouse-button defaults to 1 Example (for a Turtle instance named turtle): >>> class MyTurtle(Turtle): def glow(self,x,y): self.fillcolor("red") def unglow(self,x,y): self.fillcolor("") >>> turtle = MyTurtle() >>> turtle.onclick(turtle.glow) >>> turtle.onrelease(turtle.unglow) ### clicking on turtle turns fillcolor red, ### unclicking turns it to transparent. ondrag(self, fun, btn=1, add=None): Bind fun to mouse-move event on canvas. Arguments: fun must be a function with two arguments, the coordinates of the current point of the mouse on the canvas. num, the number of the mouse-button defaults to 1 Every sequence of mouse-move-events on a turtle is preceded by a mouse-click event on that turtle. Example (for a Turtle instance named turtle): >>> turtle.onclick(turtle.goto) >>> turtle.ondrag(turtle.goto) ### Subsequently clicking and dragging a Turtle will ### move it across the screen thereby producing handdrawings ### (if pen is down). onscreenclick(fun, btn=1) Bind fun to mouse-click event on canvas. Arguments: fun must be a function with two arguments, the coordinates of the clicked point on the canvas. num, the number of the mouse-button defaults to 1 --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.onscreenclick(turtle.goto) ### Subsequently clicking into the TurtleScreen will ### make the turtle move to the clicked point. >>> turtle.onClick(None) ### event-binding will be removed onkey(fun, key=None) Bind fun to key-release event of key. Canvas must have focus. (See method listen.) Example (for a Turtle instance named turtle): >>> def f(): turtle.fd(50) turtle.lt(60) --- THIS IS A SCREEN ORIENTED METHOD --- >>> turtle.onKey(f, "Up") >>> turtle.listen() ### Subsequently the turtle can be moved by ### repeatedly pressing the up-arrow key, ### consequently drawing a hexagon ontimer(fun, t=0) Install a timer, which calls fun after t milliseconds. Arguments: fun is a function with no arguments. t is a number >= 0 --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> running = True >>> def f(): if running: turtle.fd(50) turtle.lt(60) turtle.onTimer(f, 250) >>> f() ### makes the turtle marching around >>> running = False listen(xdummy=None, ydummy=None) Set focus on TurtleScreen (in order to collect key-events) No arguments. (Dummy arguments are provided, so listen can be passed as function argument to the onClick method.) --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.listen() (VI) SPECIAL PEN METHODS: clone() Create and return an clone of the pen, with same position, heading and pen properties. Example (for a Turtle instance named turtle): turtle = Turtle() tortoise = turtle.clone() getturtle() Return the Turtleobject itself. Only reasonable use: as a function to return the 'anonymous turtle': Example: >>> reset() >>> turtle = getturtle() >>> turtle.fd(50) >>> turtle >>> turtles() [] turtles() Return the list of turtles on the screen. Example (for a Turtle instance named turtle): >>> turtle.turtles() [] (VII) WINDOW CONTROL bgcolor(*args) Set or return backgroundcolor of the TurtleScreen. Arguments (if given): a color string or three numbers in the range 0..colormode or a 3-tuple of such numbers. --- THIS IS A SCREEN ORIENTED METHOD --- Examples (for a Turtle instance named turtle): >>> turtle.bgcolor("orange") >>> turtle.bgcolor() 'orange' >>> turtle.bgcolor(0.5,0,0.5) >>> turtle.bgcolor() '#800080' bgpic(picname=None) Set background image to image contained in gif-file picname, or return name of current backgroundimage. If picname is "nopic", backgroundimage is deleted. Argument: string, which is the name of a gif imagefile or "nopic". --- THIS IS A SCREEN ORIENTED METHOD --- Examples (for a Turtle instance named turtle): >>> turtle.bgpic() 'nopic' >>> turtle.bgpic("landscape.gif") >>> turtle.bgpic() 'landscape.gif' >>> turtle.bgpic("nopic") clearscreen() resetscreen() Reset all Turtles on the screen to their initial state. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> turtle.resetscreen() screensize(canvwidth=None, canvheight=None, bg=None) Resize the canvas, the turtles are drawing on. Does not alter the drawing window. To observe hidden parts of the canvas use the scrollbars. (Can make visible parts of a drawing, which were outside the canvas before!) Arguments: two positive integers Example (for a Turtle instance named turtle): >>> turtle.screensize(2000,1500) ### e. g. to search for an erroneously escaped turtle ;-) screen_height(self) Return the height of the turtle screen, that is of the rectangular area, which can be viewed by using the scrollbars. Example (for a Turtle instance named turtle): >>> turtle.screen_height() 600 screen_width(self) Returns the width of the turtle screen, that is of the rectangular area, which can be viewed by using the scrollbars. Example (for a Turtle instance named turtle): >>> turtle.screen_width() 800 window_height(self) Return the height of the turtle window. Example (for a Turtle instance named turtle): >>> turtle.window_height() 480 window_width(self) Returns the width of the turtle window. Example (for a Turtle instance named turtle): >>> turtle.window_width() 640 ##### Turtle - method (and also function): bye() Shut the turtlegraphics window. Example (for a Turtle instance named turtle): >>> turtle.bye() ##### Turtle - method (and also function): winsize(w, h, lr=-20, tb=-40) Reset the geometry of the turtle graphcs window. --- Arguments: w and h are the new width and height of the window, lr ('left/right') and tb ('top/bottom') are coordinates of the edges of the graphics window on the monitor-screen. + is used for left/upper edge, - is used for right/bottom edge. Example (for a Turtle instance named turtle): >>> turtle.winsize(800, 600, -10, 10) ### Resize the window to 800x600 with position ### 10 pixels from the left screen-edge and ### 10 pixels from the upper screen-edge. ##### Turtle - method (and also function): setup(self, width=0.5, height=0.75, startx=None, starty=None) Set the size and position of the main window. Arguments: width: as integer a size in pixels, as float a fraction of the screen. Default is 50% of screen. height: as integer the height in pixels, as float a fraction of the screen. Default is 75% of screen. startx: if positive, starting position in pixels from the left edge of the screen, if negative from the right edge Default, startx=None is to center window horizontally. starty: if positive, starting position in pixels from the top edge of the screen, if negative from the bottom edge Default, starty=None is to center window vertically. Examples (when used as function): >>> setup (width=200, height=200, startx=0, starty=0) sets window to 200x200 pixels, in upper left of screen >>> setup(width=.75, height=0.5, startx=None, starty=None) sets window to 75% of screen by 50% of screen and centers getcanvas() Return the Canvas, the turtle is drawing on. Just for those who like it to tinker around with (Scrolled or not) Canvas objects' --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> cv = turtle.getcanvas() >>> cv getscreen() Return the TurtleScreen object, the turtle is drawing on. Some of the RawTurtle methods - namely the SCREEN ORIENTED ones - can also be called as TurtleScreen methods. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Turtle instance named turtle): >>> ts = turtle.getscreen() >>> ts VIII. Additional features xturtle.cfg for storing start configuration utilities for creating and using docstrings in other languages will be documented soon.