The class Pen ============= ... implements a traditional turtle to do turtle graphics. It inherits from several Parent classes: class Pen(RawPen) Method resolution order: Pen RawPen 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 RawPen. NB! Those will be marked as SCRENN ORIENTED below. That means, they act on the TurtleScreen object and affect all turtles (Pens) 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 Pen objects or RawPen objects. A short note on the relation between RawPen and Pen: RawPen implements 'turtles' on a canvas (optionally a ScrolledCanvas), which has to be passed as an argument to the RawPen constuctor. Pen inherits all methods of RawPen, but drawing takes place on a (scrolled) canvas, which will be automatically generated, whenever a Pen 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 RawPen's methods (and two additional methods of Pen) are documented in functional groups as e.g. turtle movement, pen control etc. ====================================================== Methods of class RawPen (and Pen), ====================================================== 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. <<--- ------------------------------------------------------ (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 Pen 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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.heading() 22.0 >>> turtle.left(45) >>> turtle.heading() 67.0 goto(pos, y=None) setpos(pos, y=None) pos(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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.setheading(90) >>> turtle.heading() 90 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 Pen 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 Pen instance named turtle): >>> turtle.dot() >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50) (b) --- TELL PEN'S STATE position() pos() Return the turtle's current location (x,y) (as a vector) No arguments. Example (for a Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.pos() (0.00, 0.00) >>> turtle.distance(30,40) 50.0 >>> pen = Pen() >>> 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 Pen 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 Pen 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' (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 Pen 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 Pen 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 Pen 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} (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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.write('The race is on!') >>> turtle.write('Home = (0, 0)', True, align="center") (III) Pen State: (a) --- VISIBLE ? showturtle() st() Makes the turtle visible. No argument. Example (for a Pen 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 Pen instance named turtle): >>> turtle.hideturtle() (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 Pen 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 Pen 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(stretchfactor=None, outline=None) Return or set the pen's attributes stretchfactor and/or outline, 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: stretchfactor : positive number outline : positive number Examples (for a Pen instance named turtle): >>> turtle.resizemode("user") >>> turtlesize(5, 12) >>> turtlesize(outline=8) getshapes() Return a list of names of all currently available shapes. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Pen instance named turtle): >>> turtle.getshapes() ['arrow', 'blank', 'circle', 'turtle'] polystart() Start recording the vertices of a polygon. Current turtle position is first point of polygon. Example (for a Pen instance named turtle): >>> turtle.polystart() polyend() 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 Pen instance named turtle): >>> turtle.polyend() getpoly() Return the lastly recorded polygon. Example (for a Pen 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 | Pen) and thus there is NO FUNCTION of the same name. | ---------------------------------- END OF EXCURSUS <<<<<----- (D) 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 Pen 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 RawPen.delay()) Example (for a Pen 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 Pens on the Screen. Argument: None or number >= 0. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Pen 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 Pen 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) (E) USING EVENTS: IMPORTANT REMARK: All the event binding methods are SCREEN ORIENTED as above. One can think of a useful onClick method for individual turtles - alas they are not implemented! (yet?) onClick(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 Pen instance named turtle): >>> turtle.onClick(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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.listen() (F) SPECIAL PEN METHODS: clone() Create and return an clone of the pen, with same position, heading and pen properties. Example (for a Pen instance named turtle): turtle = Pen() tortoise = turtle.clone() getPen() Return the Penobject itself. Only reasonable use: as a function to return the 'anonymous turtle': Example: >>> reset() >>> turtle = getPen() >>> turtle.fd(50) >>> turtle >>> turtles() [] turtles() Return the list of turtles on the screen. Example (for a Pen instance named turtle): >>> turtle.turtles() [] (G) 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 Pen 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 Pen instance named turtle): >>> turtle.bgpic() 'nopic' >>> turtle.bgpic("landscape.gif") >>> turtle.bgpic() 'landscape.gif' >>> turtle.bgpic("nopic") clearscreen() resetscreen() Reset all Pens on the screen to their initial state. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Pen 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 Pen 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 Pen 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 Pen instance named turtle): >>> turtle.screen_width() 800 window_height(self) Return the height of the turtle window. Example (for a Pen instance named turtle): >>> turtle.window_height() 480 window_width(self) Returns the width of the turtle window. Example (for a Pen instance named turtle): >>> turtle.window_width() 640 ##### Pen - method (and also function): bye() Shut the turtlegraphics window. Example (for a Pen instance named turtle): >>> turtle.bye() ##### Pen - 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 Pen 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. ##### Pen - 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 Pen instance named turtle): >>> cv = turtle.getCanvas() >>> cv getScreen() Return the TurtleScreen object, the turtle is drawing on. Some of the RawPen methods - namely the SCREEN ORIENTED ones - can also be called as TurtleScreen methods. --- THIS IS A SCREEN ORIENTED METHOD --- Example (for a Pen instance named turtle): >>> ts = turtle.getScreen() >>> ts