> For the complete documentation index, see [llms.txt](https://www.lisppad.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.lisppad.app/libraries/lisppad/turtle.md).
# (lisppad turtle)
Library `(lisppad turtle)` implements a simple graphics pane (a graphics window on macOS, a canvas on iOS) for displaying turtle graphics. The library supports one graphics pane per LispPad session which gets initialized by invoking `init-turtle`. `init-turtle` will create a new turtle and display its drawing on a graphics pane. If there is already an existing graphics pane with the given title, it will be reused. Turtle graphics can be reset via `reset-turtle`.
As opposed to library `(lispkit draw turtle)`, this library supports an *indicator*, i.e. a symbol that shows where the turtle is currently located and whether the pen is up or down. By default, an arrow is used as an indicator. A yellow arrow indicates that the pen is down, a white translucent arrow indicates that the pen is up.
Once `init-turtle` was called, the following functions can be used to move the turtle across the plane:
* `(indicator-on)`: Show the turtle indicator
* `(indicator-off)`: Hide the turtle indicator
* `(pen-up)`: Lifts the turtle
* `(pen-down)`: Drops the turtle
* `(pen-color color)`: Sets the current color of the turtle
* `(pen-size size)`: Sets the size of the turtle pen
* `(home)`: Moves the turtle back to the origin
* `(move x y)`: Moves the turtle to position `(x, y)`
* `(heading angle)`: Sets the angle of the turtle (in radians)
* `(turn angle)`: Turns the turtle by the given angle (in radians)
* `(left angle)`: Turn left by the given angle (in radians)
* `(right angle)`: Turn right by the given angle (in radians)
* `(forward distance)`: Moves forward by `distance` units drawing a line if the pen is down
* `(backward distance)`: Moves backward by `distance` units drawing a line if the pen is down
* `(arc angle radius)`: Turns the turtle by the given angle (in radians) and draws an arc with `radius` around the current turtle position.
This library provides a simplified, interactive version of the API provided by library `(lispkit draw turtle)`.
## Setup
**(init-turtle)** 
\
**(init-turtle scale)**\
**(init-turtle scale title)**
Initializes a new turtle and displays its drawing in a graphics pane (a graphics window on macOS, a canvas on iOS). `init-turtle` gets two optional arguments: `scale` and `title`. `scale` is a scaling factor which determines the size of the turtle drawing. `title` is a string that defines the name of the graphics pane used by the turtle graphics. It also acts as the identify of the turtle graphics pane; i.e. it won't be possible to have two sessions with the same name but a different graphics pane.
**(reset-turtle)**
Closes the graphics pane and resets the turtle library.
**(turtle-window)**
Returns the window associated with the current turtle. Returns `#f` if there is no associated window.
**(turtle-drawing)**
Returns the drawing associated with the current turtle.
**(turtle-indicator)**
Returns the turtle indicator that is currently used.
## Indicators
Turtle indicators are defined and configured via record ``. Instances are created using `make-indicator`. `empty-indicator` is a predefined indicator showing nothing. `arrow-indicator` is a constructor for creating arrow indicators of different sizes.
**indicator-type-tag** 
Symbol representing the `indicator` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all indicator objects.
**(indicator? *****obj*****)**
Returns `#t` if *obj* is a turtle indicator object; returns `#f` otherwise.
**(make-indicator *****shape width stroke-color up-color down-color*****)**
Returns a new turtle indicator of given *shape* and stroke *width*. *stroke-color* is the color used to draw the shape, *up-color* is the color used to fill the shape when the pen is up, and *down-color* is the color used to fill the shape when the pen is down.
**empty-indicator**
An indicator which is not drawing anything. This is used to disable indicators fully.
**(make-arrow-indicator)** \
**(make-arrow-indicator *****size*****)**\
**(make-arrow-indicator *****size width*****)**\
**(make-arrow-indicator *****size width stroke-color*****)**\
**(make-arrow-indicator *****size width stroke-color up-color*****)**\
**(make-arrow-indicator *****size width stroke-color up-color down-color*****)**
Returns a new arrow indicator. *size* is the size of the arrow shape (12 is the default), *width* is the stroke width used to draw the shape, *stroke-color* is the color used to draw the shape, *up-color* is the color used to fill the shape when the pen is up, and *down-color* is the color used to fill the shape when the pen is down.
## Drawing
**(indicator-on)**
Show the turtle indicator.
**(indicator-off)**
Hide the turtle indicator.
**(pen-up)**
Lifts the turtle from the plane. Subsequent `forward` and `backward` operations don't lead to lines being drawn. Only the current coordinates are getting updated.
**(pen-down)**
Drops the turtle onto the plane. Subsequent `forward` and `backward` operations will lead to lines being drawn.
**(pen-color *****color*****)**
Sets the drawing color of the turtle to *color*. *color* is a color object as defined by library `(lispkit draw)`.
**(pen-size *****size*****)**
Sets the pen size of the turtle to *size*. The pen size corresponds to the width of lines drawn by `forward` and `backward`.
**(home)**
Moves the turtle to its home position.
**(move *****x y*****)**
Moves the turtle to the position described by the coordinates *x* and *y*.
**(heading *****angle*****)**
Sets the heading of the turtle to *angle*. *angle* is expressed in terms of degrees.
**(turn *****angle*****)**
Adjusts the heading of the turtle by *angle* degrees.
**(right *****angle*****)**
Adjusts the heading of the turtle by *angle* degrees.
**(left *****angle*****)**
Adjusts the heading of the turtle by *-angle* degrees.
**(forward *****distance*****)**
Moves the turtle forward by *distance* units drawing a line if the pen is down.
**(backward *****distance*****)**
Moves the turtle backward by *distance* units drawing a line if the pen is down.
**(arc *****angle radius*****)**
Turns the turtle by the given *angle* (in radians) and draws an arc with *radius* around the current turtle position if the pen is down.