S T R U C T O R I Z E R - User Guide
Features > Turtleizer

The Turtleizer component allows you to move a small green turtle over a drawing canvas and let it draw something. On execution start, the background is white, the default pen colour is black, the pen is down and the turtle is visible and placed in the centre of the Turtleizer canvas (which has a default size of about 500 x 500 pixels).

API

You can use the following instructions (note that the type specifiers int and double only declare what number type the arguments are expected in or coerced to, the type specifiers are not to be inserted into the instructions, of course):

forward(double pixel)

fd(int pixel)

Make the turtle move some pixels forward (see notes below), drawing a line segment if pen is down.

backward(double pixel)

bk(int pixel)

Make the turtle move some pixels backward (see notes below), drawing a line segment if pen is down.

right(double angle)
rr(double angle)

Rotates the turtle to the right by some angle (in degrees!).

left(double angle)
rl(double angle)

Rotates the turtle to the left by some angle (in degrees!).

gotoXY(int X, int Y)

gotoX(int X)

gotoY(int Y)

Sets the turtle to the position (X,Y).

Sets the X-coordinate of the turtle's position to a new value.

Sets the Y-coordinate of the turtle's position to a new value.

penUp()

The turtle lifts the pen up, so when moving no line will be drawn.

penDown()

The turtle sets the pen down, so a line is being drawn when moving.
hideTurtle()
Hides the turtle.
showTurtle() Show the turtle again.
setPenColor(int red, int green, int blue) Set the default pen colour to the given RGB value (range 0...255 per argument). This colour is used by undyed move commands.
setBackground(int red, int green, int blue) Set the background colour to the given RGB value (range 0...255 per argument).
clear() Wipe the canvas from all traces of the turtle (without changing its remaining status; versions > 3.28-06 only).

Three functions are available to retrieve the current position and orientation of the turtle (since release 3.27):

double getX()

Returns the current horizontal position (may be between pixels).

double getY()

Returns the current vertical position (may be beztween pixels).

double getOrientation()

Returns the current turtle orientiation in degrees (in degrees, range -180...180).

Since version 3.27-05 you have the opportunity to address the Turtleizer routines under individually configurable alias names. You may specify and activate your favourite aliases via menu Preferences => Controller Aliases ....

Please note that:

  • Procedures forward and backward are not exact synonyms for fd and bk, respectively, but work with an internal floating-point coordinate model, which is way more precise than the strict (but somehow inconsistent) integral pixel model still used by fd and bk. Remember that e.g. a walk to the next neighbouring pixel in diagonal direction hasn't a length of 1 pixel but √2. Hence, going a way of integral length in an awkward angle won't exactly end where we think it does, only axis-parallel moves will definitely have exact integral length. Coercion differences < 1 pixel may sum up to enormous deviations on complex drawings, particularly with a lot of short moves. With a floating-point coordinate model, in contrast, the virtual position is not necessarily at an exact pixel position but consistent to the previous moving directions and lengths, which is important for the moves to come. Having both models available now, you may study the differences. (Via the menu items Edit =>  To fine graphics and Edit =>  To integer graphics you may convert your diagram code from the one paradigm to the other and vice versa.) But be aware that any call of fd, bk, or one of the goto* procedures will coerce the respective target position to an integral pixel coordinate, also as starting point for subsequent floating-point moves.
  • The default pen color for forward/backward/fd/bk commands is black. If you want the turtle to draw a coloured line segment, just colourize the respective element inside the diagram. You may also set the default pen color to a different RGB value, using setPenColor(r, g, b). All forward/backward/fd/bk commands in undyed diagram elements will then use the default color most recently set, whereas move instructions in colourized elements will still draw segments in their respective element colour.
  • The Turtleizer is based on the Executor, so any constraints of the latter apply here, too, especially the parser preferences have to be configured correctly.
  • Negative values for pixel numbers and angles are allowed and will be equivalent to the corresponding positive value in the inverse procedure call, i.e. right(-angle) = left(angle)forward(-pixel) = backward(pixel), and vice versa.
    Negative argument values in setPenColour or setBackgroud will simply be replaced by their absolute amount.
  • Omitted arguments are interpreted as 0.
  • The calls of the built-in procedures listed above must not be placed in Call elements but ordinary Instruction elements.
  • The goto procedures (gotoX, gotoY, gotoXY) will never draw anything - no matter whether pen is up or down. Don't forget that the coordinate origin of drawing canvases is the upper left corner and Y coordinates grow downwards.
  • The background colour imposed by procedure setBackground will last till next setBackground call.
  • The angle returned by getOrientation() is 0 if the turtle looks upwards (north), it is positive while the turtle looks to the right (clockwise) and negative while the turtle is turned left (counter-clockwise).

In order to execute an algorithm containing some of the Turtleizer procedures listed above you must have pressed the button Turtleizer launch button to open the Turtleizer window first. This will automatically open the Executor Control panel as well. While the Turtleizer window is open it will then be sufficient just to invoke the Executor Control panel via button  for another start. Without the Turtleizer window being open, the Turtleizer procedures won't be recognised and will cause errors on execution attempt.

Example

The following algorithm draws a little hut with base hight and width from input with a triangular roof (having a right angle at top):

DrawHut algorithm

The drawn image with width = 200 and height = 100:

Turtleizer window with drawn hut

Diagram code change helper (Turtle with a Archimedian spiral,Turtle with a rectangular spiral)

If you want to study the consequences of the pixel coercions with an integral coordinate model in comparison to the floating-point coordinate model or if you happened to use the brief command names in earlier diagrams but want to change to the floating-point model, then two new menu items Turtle with a Archimedian spiral and Turtle with a rectangular spiral in the "Edit" menu will help you:

Turtle with a Archimedian spiral replaces all occurrences of the Turtleizer procedures fd and bk within the selected element range by forward and backward, respectively;

Turtle with a rectangular spiral does it the other way round (i.e. replaces forward with fd and backward with bk).

If you have selected a structured element, say a loop, then all directly and indirectly contained instructions are involved, but not so instructions in called subroutines. In order to convert all instructions of the entire diagram at once, simply select the framing program or routine element. These instruction replacements may also be induced by key bindings <Shift><G> and <Ctrl><G>, respectively. They are fully undoable and redoable.

A preliminary check whether the selection contains any relevant Turtleizer instructions at all is done to prevent you from inducing void undo or redo entries. After the conversion, a message box will pop up, telling you how many replacements were done.

Export

In exported code, the Turtleizer API will usually not work, of course, since the procedures and functions aren't native code in the target language. Possibly, however, you may happen to find some adaptable Turtle application in the wideness of the internet for your target language and manage to integrate it.

For Java and C++, however, there are exactly compatible source packages available. See Export Source Code for details and links.