Turtle Graphics Implementation
What's New?	Products		Totally Objects Downloads	Other Downloads	Consultancy	VAST Training
Educational Discounts	See what our clients think		Buy	News Groups	Consultant's Pack	Contact Us

VisibilityTurtle is a new class that has been added to Visibility to provide an interface into Turtle Graphics.

There are three categories of public methods in the class comprising of:

Public Categories

VisTurtleCommands - overall description and background

Click here for a full list of commands

These commands basically tell the turtle what to draw.

Pen Control

To start with there are commands that manage the pen. The two main ones are penUp and penDown. When the pen is up, nothing is drawn. When the pen is down, drawing can take place. There is an additional command that adjusts this - lines / noLines. The problem here is that, with the pen down, under normal settings, everything will be drawn. This means that when you are configuring a page of text with, say, no graphics at all, everytime you move the turtle, you would have to issue a penUp command and then a penDown when you wanted the next line of text to be displayed. This is extremely tedious. Thus, the lines / noLines pair of commands adjust the pen state to affect only graphics. If you send penDown; noLines then only text and images will be displayed. All other turtle movements will not result in any output. Once you want to draw a line or a box, issue lines; and the objects will start to appear again.

Drawing objects

All drawing commands have a hierarchy of methods that increase in complexity. The lowest option uses as many defaults as possible, whilst the highest provides almost total control of all elements of an object. To demonstrate, look at the methods for drawing a box. There are three basic methods: drawBox, drawOpenBox and drawFilledBox.

drawBox - draws a box using all of the current defaults, which include the fill setting, the fill color and the box size
drawOpenBox - is the same as drawBox but overrides the fill default to false - no fill
drawFilledBox - is the same as drawBox but overrides the fill default to true - fill

The next three methods up the hierarchy are:

drawBox: boxExtent - draws a box using all of the defaults except the size of the box
drawBox: aBoxExtent fill: aFill - draws a box using all of the defaults except the size of the box and the fill
drawBox: aBoxExtent color: aColor fill: aFill - draws a box using the supplied size of the box, the fill color and the fill

You will find similar patterns with all of the other drawing commands, including those for text.

What objects can be drawn?

The list of objects available is as follows:

• Box (standard, 3D or with a shadow)
• Circle
• Ellipse
• Image (single or tiled)
• Line (solid, dashed, with or without arrowheads)
• Polygon
• Text (single line or word wrapped into an area)

Note: Lines are not drawn explicitly - they are drawn by moving the turtle with the pen down.

Images

Drawing Images

It is possible to place an image of any type supported by IBM Smalltalk on the page. The list of supported items comprises TIFF, JPEG, PCX and GIF and BMP. The suffix of the file name is irrelevant as the code can resolve which file type is being offered by its format. Images can be placed using a built in justification scheme. The justification options are left, right and center plus stretch or tile. Left right and center affect how the image is placed within the bounding box (which does not have to be the same proportions as the image itself). Use of these three ensures that the image is placed to fill the bounding box as best as can be done meeting the given justification. If you want the image to fill the box then use the stretch option. This will result in a distorted image if the bounding box doers not have the same shape as the image. Lastly, tiled will place the image - retaining its natural size and proportion - and tile it into the given bounding box.

Loading Images

Images can be loaded into the system in a two ways:

1. Directly into the object using drawImageFromPath: aPath. This does draw the image immediately but it does not cache the image, which means that, for it to be used again, it must be loaded again. If the file in aPath does not exist, a box with a cross will be printed instead, showing that the image is missing.
2. Internally to VisibilityTurtle, there is a dictionary of images. You can load images at any time in the process (before using them to draw of course) into this dictionary. Use the loadImage: aPath as: aKey command for this, where aKey is a string containing any unique name you wish to give this particular image. To use images stored in this way, use the drawImageFromKey: aKey command. 

Text

Drawing text

Text may be placed anywhere on the page using the text: aString command. This takes the string argument and outputs it at the current turtle location using all of the current defaults. These defaults include the font, justification and color. Also, the text will be drawn at the current turtle angle. Justification can be left, right, center or decimal (for numbers only - they will justify on the decimal point - if you set decimal for any other text it will result in right justification). Note that the justification settings use Visibility formats so the settings are ##l, ##r, ##c and ##d. Text can also be placed within a given width. The text given will then be word wrapped into a box that matches that width but has sufficient depth to display all of the text. This is done using the text: aString into: aWidth command.

Loading text

Like images, text can be loaded from external sources in a variety of ways:

1. Directly to the display from a file path using textFromPath: aPath. If the file doea not exist then a blank string will be drawn.
2. Internally to VisibilityTurtle, there is a dictionary of text strings. You can load strings at any time in the process (before using them to draw of course) into this dictionary. Use loadText: aPath as: aKey command for this, where aKey is a string containing any unique name you wish to give this particular string. To use text stored in this way, use the textFromKey: aKey command.
3. Load a file containing many entries directly into the text dictionary. Use the loadTextDictFromPath: aPath command for this. The text file should have the format
   stringA = This is string A
   stringB = This is string B
   In other words, each string should be on its own line in the file separated from its key word by space=space.
   This process will add to any entries already in the dictionary so multiple loads can be made in this fashion.

Movement commands - turn and move

There are two movements associated with the turtle directly - moving and turning. 

turn: 45
move: 20
penUp
and so on...

These all use real world measurements, so turn: 45 tells the turtle to turn 45 degrees. If the turtle was currently facing 132 degrees then it will turn to 177 as a new heading. There is a corresponding turnTo: aHeading command which will give the turtle an absolute heading to face, thus turnTo: 45 with cause the turtle in the previous example to turn from 132 degrees to 45 degrees; i.e the equivalent of turn: -87. The move command operates in a similar manner except that the number provided can be supplied in pixels, inches or millimeters, so if the movement setting is millimeters, then move: 20 with instruct the turtle to move 20 mm along the current heading. There is a corresponding moveTo: aPoint command whereby moveTo: 20 @ 50 will instruct the turtle to move to a location 20mm across the page from the top left hand corner and 50 mm down. The turtle will maintain its previous heading, so if it was facing 45 degrees before this, then it will still be doing so.