# Qogo Help

## Overview

Qogo (Pronounced kwo-go is a Langiage based on a mix of Tcl and Logo.

It implements the Turtle graphics primatives for drawing on a canvas.
The program has been designed to teach 8 to 10 year olds the principles of programming.
That is Sequence, Selection , and Iteration

The program can be used to design complex pictures using simple commands.

## Introduction

The Application is designed to teach children of age ranging from 5 to 10 years old the basics of programming.
It does this by representing the contructs in as simple a way as possible. The Application teaches both programming as well as simple geometry without the complexities of trigonometry.
It also helps with imagination as the symbols on the screen are abstract concepts.

### The Turtle Concept

On the screen is a Turtle represented by a triangle shape. The turtle can be made to draw shapes on the screen by issuing a sequence of instructions. The Turtle carries a selection of pens and can select one to draw in different colours and widths.

To draw simple shapes that use onle horizontal lines only four simple commands need to be understood. These are Forward, Right, Pen up, Pen down, as an example ,. to draw a square of one grid unit you would issues the following instructions:

Forward 1 Right 90 Forward 1 Right 90 Forward 1 Right 90 Forward 1 Right 90
The Turtle by default starts out with the Pen down.

Unfortunately when more complex shapes are tried and angles other than 90 degrres are involved there is no simple way of calculating how far forward to move the turtle to make lines that would connect with the grid. To solve this problem the concept of a Puppy is introduced and explained below.
It is suffice to understand that the Puppy allows diagonal lines to be drawn without having to use angles or square roots.

#### The Puppy Concept

The Turtle has a Puppy that normally walks around underneath the Turtle so is not seen. The Puppy is represented by a square on the screen.

The Puppy only understands two instructions, PuppyStay and PuppyCome.The puppy concept operates as follows.

1. After issuing the instruction PuppyStay, the Puppy becomes visible and takes the pens from the Turtle
2. Now when the Turtle moves the Puppy symbol remains stationary on the screen.
3. While the Puppy is staying the Turtle cannot draw as the Puppy has the pens!
4. Once the instruction PuppyCome is given, the Puppy walks to the Turlte taking the most direct path and draws a line in the colour that was selected when the instruction PuppyStay was given.
5. The Puppy then gives the pens back to the Turtle and then hides underneath so it is not seen anymore.

Back to Contents

## Installation

If you are reading this document from the help button of the application then you can skip this section.

The program is distributed as a zip file from here.

Under Windows Locate the folder in Explorer and click on the file Qogo.tcl. The application window should appear.

Under unix based systems, perform above and change to the qogo directory and run the command wish Qogo.tcl

### Resources

The program uses sqlite and the htmlwidget packages. Binaries of these libraries are included in the distribution. They will be used in preference to any other copies on the machine as sqlite keeps changing the database format.

Back to Contents

## What you see on the screen

The screen layout is as follows:
 1 Button Row 1 2 Button Row 2 8 Options 3 Command List 9 Parameters 5 Drawing Area --------------------------------------------------------- 4 ProgramList 6 Command Entry: 7 ------ Status Messages --------

Where:

1. Extra Buttons
2. Main Buttons
3. The list of command words understood by the Qogo interpreter.
4. The list of commands that will be executed when Run is pressed.
5. The canvas where drawings are made.
6. Commands can be typed into this box and a placed into the Program List when the Enter key is pressed.
7. Status messages are displayed in this box.
8. Options
9. Parameters for the current programme

Back to Contents

### Main Buttons

These are the buttons that you will mostly when operating the program. Their function is outlined below.

• ++
Clicking this button enlarges the picture in the drawing window (makes it look bigger). The scroll bars around the drawing box can be used to see parts of the picture that are no longer visible on the screen.

• --
This does the opposite of the ++ button. It makes the picture smaller so more of it is visible.

• =1
Returns the picture to the normal size.

• Undo
Undoes the last program step that was entered into the Programme list.

• Run
Executes the list of instructions in the Programme list one wafter the other. After each instruction the screen updates to show what was drawn by that instruction.

• Clear
Erases the picture.

• Show
Makes the Turtle visible.

• Hide
Makes the Turtle invisible. The picture will draw much faster.

• Find
Locates the Turtle and scrolls the drawing so that the Turtle can be seen.

• Home
REturns the Turtle to it's starting position. It does not draw when returning.

• Halt
Stops the current program that was started by the Run button. Some instructions can take a long time to execute so it may not stop immediately.

Back to Layout

### Extra Buttons

Buttons that are not used as often.

The four buttons located next to the word Test all operate on test files. A Test is a drawing that has been saved and can be used as a pattern that someone has to fry and follow.

• Check
This will perform a check of the current drawing with the current pattern. If they match a message is shown. Areas that do not match are marked on the drawing. a Red line indicates part of the pattern that was not traced. A Black line indicates an extra line that is not in the pattern.

• Clear
This erases the Read and Black marker lines generated by the Check button.

This displays a dialog of available test files and allows one to be selected and then loaded. The pattern draws with broken lines as to distinquish the pattern from the actual drawing.

• Save
This takes the current picture and saves it as a test. A new names is chosen for the test and once saved the picture can be loaded back as a test pattern.

The two buttons located next to the word Programmes all operate on test files. A Test is a drawing that has been saved and can be used as a pattern that someone has to fry and follow.

This displays a dialog of available programme files and allows one to be selected and then loaded. The instructions for the programme will be placed into the Programme List box and the programme will be executed with it's default parameters.

• Save
This takes the list of instrcutions from the Program List box and saves them to a file. A new names is chosen fot the instruction list and this becomes a new command word. This word will automatically be loaded when this application is restarted. From now on the name can be used as an instruction.

The four buttons located next to the word Pics all operate on picture files. The current picture can be saved and reloaded as a background that stays even after a new picture is drawn and erased.

This displays a dialog of available pciture files and allows one to be selected and then loaded. The picture will now become a backdrop for any new picture made. This backdrop will print out with any new drawing made over the top of it.
The current drawing can be saved as a new picture to make composite pictures.

• Save
This saves the current drawing as a picture file. A new name is given for referring to the file when loading back in.

• Clear
Erases the currently loaded picture from the drawing. It does not remove the picture from the disk where it was saved.

• Print
Prints the current drawing to the printer. This requires setting up for each computer the program is installed on.

The Button labeled Help displays this help screen.

Back to Layout

### Qogo Instructions

The list that appears on the very left of the display is the list of known Qogo instructions. Following an instruction may be 1 or more question mark (?) symbols. These stand for parameters that must be added to the instruction before it can be run.

IE
The forward command need to know how far? to go, so a number representing the number of grid spaces to advance is supplied as the first and only parameter.
For Example.
Forward 1 - Moves one space
Right 90 - Turns right by 90 degrees. Repeat 4 {Forward 1 Right 90} - Repeat 4 times the sequence Forward 1 Right 90.

When an instruction is selected , the parameter names are displayed in the Status message box as a hint as to what information should be supplied as arguments.
See Syntax for a command summary

### Current Program

This is the sequence ( a list) of instructions that have been requested to be performed when the run button is clicked. Either they have been entered from typing into the Comand box or by clicking instructions in the Command words box.

### Drawing Area

The results of the instructions are displayed in this area. The display is divided into squares called a grid. Each instruction operates in grid units. To change the visible size of the image use the ++ and -- buttons.

### Command Entry

When the cursor is focused on this box, Instructions can be typed in. On pressing the Enter key, they are executed and transferred to the Program list box.

More than one instruction can be given on a single line and they will be executed together.

When the run button is clicked each line is executed and then the screen is updated. If all the instructions are entered on one line, the picture will not show until all the drawing command have been completed.

When typing the Tab key may be pressed to complete the typing of the instruction. If the part of the word typed matches more that one command then both commands will be highlighted and only the part of the word that is common to both instructions will be typed in automatically.

### Status Messages

Information that has no were else to be displayed is placed in this box at the bottom of the display.

### Coloured buttons

The coloured buttons are short cuts for changinfg the colour of the pen. Clicking on the button changes sets the pen colour. Clicking with the right mouse button changes the background colour of the drawing area.

### Environment options

The operation of the application can be changed by these settings:

1. Grid
Shows the grid lines on the screen. This is usefull for working out relative placement of objects in a pattern to work out how far to travel.
2. Show
Causes the screen to be updaded as it is drawn. This is usefull to see where in the sequence that a mistake has been made. Turning it off allows the picture to be drawn much quicker.
3. Test
When turned on, will automatically perfrom a Test / Check. And see if the drawing matches the currently loaded pattern. It also causes the picture to be erased prior to running the instructions.
4. Debug
Shows the programmer why the application is not doing what he wanted. Of no use to anyone else. Leave Turned off as having this option turned on will slow down drawing.

### Programme Parameters

This box is used when creating a new instruction word. See command parameters in the Syntax section for more information.

## Mouse buttons

### Instruction list

• Left Mouse
Places command in Command Entry box.

### Programme list

• Left Mouse
Selects or unselects instruction entry and places it in the command entry box.

• Right Mouse
Executes the instruction immediately. Can be used for single stepping

• Shift-Left Nouse
Inserts a new instruction before instruction under mouse pointer.

• Double Right Mouse
Deletes instruction under Mouse pointer.

Back to Content

## A Sample Programme

A Simple introduction to the application.

1. Load a test program by clicking on the Load button in the group of four buttons to the immediate right of the word Test: located in the Extra Buttons box.

2. From the list click on Test-1.tst.

3. Click the Ok button.
The display should now show a blue dotted square with the Turtle located at the bottom left pointing north (up the screen).

4. Locate the instruction Forward 1 in the Program List box.
Click on the instruction. It should now appear in the Command Entry box at the bottom of the display. Since we do not require to change the ammount, press Enter.

The command should now appear on the Program List box.
Also the turtle should have executed the command.

5. Locate the instruction Right 90 in the command List box.

6. Click on the instruction, and Press Enter.
There should now be two instructions in the Progame list box , and the turtle should have drawn the left side of the square and now be facing west (along the top of the square).

7. Repeat entering the above two instructions to go around the box.

8. When completed press the Run button. The drawing should erase and then the turtle should make the pattern as it executes the list of instructions.

9. A message should display indicating the you have made the pattern correctly.
If the image on the screen is too small, click the ++ button to make it bigger.

### Creating you own instructions

The above instructions can be saved under a given name. This name then becomes an instruction that can be typed in. The one name will execute all the instructions

### Command Parameters

Design a new instruction that draws a circle as a series of steps.

Whout being able to supply parameters to the instruction, we would have to create a new instruction for each size of circle we wanted to draw.

We use the box above the Program List box to specify parameters that will be supplied to the new instruction should it be saved.
The format of the parameter list is :

Name Value Name Value

As many parameters as required may be specified. The Name can be any string that does not include space or tab characters.
It is recommended that names should be in lower case.

#### Special Case

A Special character ^ is reserved as a prefix to the name for use in the following case.
When the parameter is designed to not be a number, the name should be prefixed with ^.

Note this only applies to the name given in the Parameter box, do not prefix the parameter name with a ^ when referencing it from the program.

The reason why this is necessay is outside the scope of this document. It is suggested that you look at the instructions for commands such as DoCircle and GoAround to see why when this obfuscated syntax is required.
If you are only ever expecting numbers as parameters then you can ignore the use of ^.

Back to Contents

## Creating Tests

Tests can be created simply by drawing a shape and then saving it using the Test Save button.
The file can then be loaded using Tests Load and it will now appear drawn with dashed lines.

Back to Contents

## Syntax

The syntax can be though of as Backwards Forth .
It consists of a stream of tokens that are consumed from left to right.
The First token in the list is the name of a command that is called with the rest of the tokens as parameters. The command consumes as many of these parameters as required and performs its function. Before returning to it's caller the command will execute all parameters that have not been consummed.
Each parameter that is consumed is evaluated as a number. If the token is not a number or a known variable then the token is executed as a command.
Commands that are called with insufficient parameters, steal parameters from the command that invoked them.

An example, consider :

Right Div Sub 100 10 2 Forward 1
1. First the command Right is invoked with the parameters Div Sub 100 10 Forward 1
2. The command Right removes one token Div as the number of degrees in which to turn.
This leaves Sub 100 10 2 Forward 1
3. Right evaluates the parameter which is not a number so it is executed.
4. The command Div is called with no parameters.
5. So it steals Sub from its caller (Right)
6. Div evalutates the first parameter Sub and it is not a number so executes it.
7. The command Sub os now called with no parameters.
8. Sub now steals 100 and evaluates it. It is a number so no processing occurs.
9. Sub now steals 10 and evaluates it. It is a number so no processing occurs.
10. Sub performs the subtraction and returns 90 to its caller (Div)
11. Div now sets its first parameter to the value returned by Sub (90).
12. Div now steals another parameter 2, and since it is a number no more processing occurs.
13. Div now performs the division and returns 45 back to it's caller (Right).
14. Right now assigns the returned value to its parameter.
15. Right only needs one parameter.
16. Right performs the turn (by 45 degrees).
17. Right now executes the remaining parameters Forward 1
18. The Forward command needs one parameter which is has and it is anumber so just uses it.
19. Forward moves 1 grid space forward.
20. Forward has no parameters left so returns.
21. Right now returns.
What is not stated in the above is that after each parameter is taken from the list it is instantly removed from the argument list and evaluated before the next parameter is taken from the list.
Only one parameter is taken at a time an evalutated so that if any parameters are removed by the evalutation process they are removed from the list before the next token is chosen.

For the purpose of animating the process of drawing the application allows the program to be broken into a number of lines, with each line having one or more commands.

For the purposes of explaining how the intperpreter works, it should be assumed that the program is one continuous list of tokens that are executed with one invokation.

### Instruction Words

There are only eight core instructions. These are

• Pen up
• Pen Down
• Forward
• Right
• Colour
• Width
• Clear
• Home

There are mirror image commands for convienience:

• Backward
• Left

To save typing there are these commands

• Repeat
• Loop

All other instructions are based on these. All instructions begin with a capital letter.
The following table descibes each command , its parameters, and its purpose.
 Pen updown Drawing only happens when the pen is down. Use Pen up to move without leaving a trail. Forward amount Moves in the current direction, amount number of grid spaces. Colour ^type Changes the pen colour, Valid colours are: red blue green yellow purple white black brown Home Return the turtle to the starting position without drawing any trail. Clear Erases all the lines in the drawing. Width n Erases all the lines in the drawing.Makes the pen x pixels wide. Repeat num ^what Repeats the instruction what num number of times.To repeat more than one instruction , enclose them between { and } characters In the Program List and alternate format may be used. What may be omitted and furhter in the list a End Repeat instruction may be inserted. All instructions between the Repeat and End Repeat will be repeated. Note that this is only down for ease of entry. A variable called Loop is incremented by one for each iteration of repeat. To make a square use Repeat 4 {Forward 1 Right 90} Loop ^var start end incr ^what Repeats the instructions contained in what. At the start sets the variable called var to the value start. After each loop the variable is incremented by incr. If the new value is less then end the loop continues. To make a spiral use Loop I 1 20 1 {Forward I Right 90} The following are basic mathmatic instructions. Add+ num1 num2 Returns the sum of num1 and num2 Sub- Returns the difference of num1 and num2 Mul* num1 num2 Returns num1 multiplied by num2 Div/ num1 num2 Returns num1 divided by num2 Short cut Commands GoAround ^dir steps ^what Turns around a circle in steps steps. At each step execute the commands in what For example do draw a square use GoArround Right 4 {Forward 1} Circle size Draw a circle centered on the current position of diameter size The global variable Steps determines the number of steps taken to draw the circle. If Steps is 8 then an Octagon would be drawn. DoCircle size ^pen ^what Like circle but at each virtex, the command what is executed. To Draw a Hexagon of Triangles use Steps 6 DoCircle 6 down {Steps 3 Circle 1} If up is specified for pen, no lines will be drawn between points on the circle. Guess Choose a colour randomly. Setv ^var value Sets a global variable var to the value given value SetL ^var ^val Sets the global variable var to the literal val HalfCircle size Draws a half circle to th Right of the current position. If expr ^what If expr evaluates to true then execute what. An alternate form can be used in the Programme list. If what is ommitted and the instruction End If is placed in the list, then all the instructions between the If and End If become the what parameter. IfNot expr ^what If expr evaluates to false then execute what. Trigonometry Commands Sin angle Returns the sine of angle , where angle is in degrees Cos angle Returns the cosine of angle , where angle is in degrees Tan angle Returns the tangent of angle , where angle is in degrees ATan x y Returns the angle whose tangent is x / y , Sqrt x Returns the square root of x Miscelleanous Commands Text size ^txt Adds the characters txt size grid units high Example usage Text 1 {Hello World} SP Moves one grid space to the right without leaving a trail. Z A C The Letters Z, A, and C with spaces. Scale x Makes the length of all moves x times longer. Steps x Sets the global variable Steps which is used by some commands to determine how many sides a polygon is drawn with. It is short cut for Setv Steps x To draw a square use Steps 4 Circle 1 To draw a triangle use Steps 3 Circle 1 To draw a octagon use Steps 8 Circle 1 To draw a circle use Steps 32 Circle 1 NilNull The null value. Nuls cannot be used as arguments. This variable is used to pass {} as a parameter to a function.

Back to Contents

## Credits

Parts of this programme were developed with Open Source software and the source for these parts are included in the distribution.

I would like to aknowledge all those that have contributed ideas and techniques to the TCL Wiki as they may have lead to improvements in this code.