# 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) [procedure]
(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) [procedure]

Closes the graphics pane and resets the turtle library.

(turtle-window) [procedure]

Returns the window associated with the current turtle. Returns `#f` if there is no associated window.

(turtle-drawing) [procedure]

Returns the drawing associated with the current turtle.

(turtle-indicator) [procedure]

Returns the turtle indicator that is currently used.

## Indicators

Turtle indicators are defined and configured via record `<indicator>`. 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 [constant]

Symbol representing the `indicator` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all indicator objects.

(indicator? obj) [procedure]

Returns `#t` if obj is a turtle indicator object; returns `#f` otherwise.

(make-indicator shape width stroke-color up-color down-color) [procedure]

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 [constant]

An indicator which is not drawing anything. This is used to disable indicators fully.

(make-arrow-indicator) [procedure]
(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) [procedure]

Show the turtle indicator.

(indicator-off) [procedure]

Hide the turtle indicator.

(pen-up) [procedure]

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) [procedure]

Drops the turtle onto the plane. Subsequent `forward` and `backward` operations will lead to lines being drawn.

(pen-color color) [procedure]

Sets the drawing color of the turtle to color. color is a color object as defined by library `(lispkit draw)`.

(pen-size size) [procedure]

Sets the pen size of the turtle to size. The pen size corresponds to the width of lines drawn by `forward` and `backward`.

(home) [procedure]

Moves the turtle to its home position.

(move x y) [procedure]

Moves the turtle to the position described by the coordinates x and y.

(heading angle) [procedure]

Sets the heading of the turtle to angle. angle is expressed in terms of degrees.

(turn angle) [procedure]

Adjusts the heading of the turtle by angle degrees.

(right angle) [procedure]

Adjusts the heading of the turtle by angle degrees.

(left angle) [procedure]

Adjusts the heading of the turtle by -angle degrees.

(forward distance) [procedure]

Moves the turtle forward by distance units drawing a line if the pen is down.

(backward distance) [procedure]

Moves the turtle backward by distance units drawing a line if the pen is down.

(arc angle radius) [procedure]

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.