## `plot::Turtle` -- graphical primitive for turtle graphics

#### Introduction

`plot::Turtle``()` creates a turtle, which is a drawing device which understands few simple commands.

#### Creating Elements

`plot::Turtle()`

#### Related Domains

`plot::Lsys`, `plot::Scene`

#### Related Functions

`plot`

#### Details

- Objects generated by `plot::Turtle` represent a simple drawing device called a turtle. A turtle may be used to create 2-dimensional line drawings.
- A turtle has a position in the plane, a direction and a colour. It understands only few commands: Move forward and draw a line, move without drawing, turn left, turn right, change your colour. Further a turtle may remember its current state (position, direction and colour) by pushing it onto a stack and change its state to a former one by popping it off from the stack.
- One may display the path which a turtle has been taken since its creation using the function `plot`. One may also insert a turtle into a graphical scene of the `plot` library like any other graphical object.
- The state of a turtle may be changed by procedures which are called methods of the turtle. These methods can be accessed via the slot operator `::`. One method of a turtle for example has the name `line`. With the call `t::line(1)` one causes the turtle `t` to draw a line of length 1 in its current direction.

  The following methods are available for a turtle `t`:

- `t::color(c)` changes the actual colour of the turtle `t` to `c`. The colour must be given as a list of 3 real-valued numbers in the range between 0 and 1, similar to the other colour values of the plot library.

  The method returns the turtle.

- `t::left(deg)` changes the direction of the turtle `t`. It rotates left for `deg` degrees.

  The method returns the turtle.

- `t::right(deg)` changes the direction of the turtle `t`. It rotates right for `deg` degrees.

  The method returns the turtle.

- `t::line(len)` causes the turtle `t` to move forward in its current direction, drawing a line in its current colour. The length of the line is `len`.

  The method returns the turtle.

- `t::move(len)` causes the turtle `t` to move forward in its current direction without drawing a line. The length of the move is given by `len`.

  The method returns the turtle.

- `t::push()` causes the turtle `t` to save its current state, i.e., its position, direction and colour. The state is pushed onto a stack.

  The method returns the turtle.

- `t::pop()` restores the state of the turtle to the one which is currently stored on the stack. The top element of the stack is popped off the stack.

  The method returns the turtle.

- The initial state of a turtle after creation is the following: It is located at the origin, heading north in the direction of the point (0,1). Its colour is green.
- An object of `plot::Turtle` has type `"graphprim"`, i.e., if `o` is such an object, then the result of `type(o)` is the string `"graphprim"`.

#### Result of Evaluation

Evaluating an object of type `plot::Turtle` returns itself.

#### Method getPlotdata: create the plot data of a turtle

- `getPlotdata(dom t)`
- - Returns a list of an inner list, where the inner list is a plot description of `t` in a `plot2d` and `plot3d` conforming syntax, respectively, i.e., it has the form `[Mode = List, [polygon(...)], ...]`.
  - This method is called from `plot::Scene` to build the plot data of the graphical scene.

#### Method slot: read turtle methods

- `slot(dom t, string slotname)`
- - Reads the value of the slot `slotname` of `t`. `slotname` must be the name of a method of the turtle, see above.
  - If `slotname` is an invalid method name, then an error message is issued.
  - This method overloads the system function `slot`, i.e., one may use it in the form `t::slotname_id` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(t, slotname)`.
  - One may not change a turtles method or state using the slot function.

#### Method print: print a turtle

- `print(dom t)`
- - This method returns a string representing the turtle. This string shows the turtles current position and direction, but not the other aspects of its state, like the path which has been taken by the turtle in the past. It is used to print objects of `plot::Turtle` to the screen.
  - See the system function `print` for details.

#### Example 1

We create a turtle, let it draw a triangle and then show its path:

    >> T := plot::Turtle():
       T::right(90): T::line(1):
       T::left(120): T::line(1):
       T::left(120): T::line(1):
       plot(T, Axes = None)

#### Example 2

We draw a star-like object:

    >> T := plot::Turtle():
       for i from 1 to 36 do
           T::right(170); T::line(1)
       end_for:
       plot(T, Axes = None)

#### Changes

- used to be called `Turtle`
- Adapted to comply with the `plot` library.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000