A First Program

Let's create a simple program in Codea.

Step One: Launch Codea

Launch Codea on your iPad. The screen will look a bit like the following (if this is the first time that you have used Codea then there will only be one square in the lower row).

Step Two: A New Project

Now touch the green square with the white cross at the left of the lower row. It says "Add New Project" underneath it. This brings up the New Project dialogue. Touch the screen where it says "type project name here". This brings up the keyboard where you can type in a project name. Spaces are allowed. Once you've chosen your name, either touch "Done" on the keyboard or "Create" in the New Project dialogue.

Step Three: The Initial Code

This brings up the initial code for your new project. Your project can consist of several files, the initial one is called "Main" - you can see this name at the top of the screen. If you add more files these will be listed in alphabetical order across the top. Your main file will already have some code in it, helpfully supplied by the Codea team. It will look a little like the following:

-- Use this function to perform your initial setup
function setup()
   print("Hello World!")
end

-- This function gets called once every frame
function draw()
    -- This sets a dark background color 
    background(40, 40, 50)

    -- This sets the line thickness
    strokeWidth(5)

    -- Do your drawing here
end

The main differences between what you see and the above are the colours and the line numbers. On the left-hand side of the screen, next to the code, are the line numbers. This helps navigation. Note also that there are triangles next to the lines where the word function appears.

Step Four: Running the Program

Run this program by pressing the arrow at the bottom right of the screen. If you happen to have the keyboard in view then the arrow is at the top right of the keyboard. You will (hopefully) see the following screen (note that the orientation is fixed). It's not all that interesting, but you should take note of where the string "Hello World!" ends up. The big black square that occupies most of the screen is the canvas: it is where all the drawing things get drawn. As we don't yet draw anything, it is blank. We can fix that now.

Step Five: Editing the Program

Go back to the editing page by touching the "BACK" button at the lower right of the screen (assuming that you're holding the iPad in the right orientation for the display). Let's now add some code!

In this first example, we're just going to draw something on the screen. So touch the code at that blank line just under function draw(). This should bring up the keyboard and place the cursor at the start of the line (a blinking vertical blue line). Also, the line number is slightly highlighted on the left. Let's get into good habits right from the start so press the "tab" button to correctly indent your code. The "tab" button is at the left-hand end of the row of extra keys that Codea supplies just above the regular keyboard. Let's go wild and draw a circle. Start typing the word "ellipse" (a circle is a special kind of ellipse). As you type, you'll see that Codea guesses what word you're typing. If you want, you can choose it from the list.

Now an ellipse has to have a centre and a size. To specify those, we give a list of options following the word ellipse. To ensure that the ellipse knows that these options are for it, we enclose them in parentheses. As adding balanced parentheses (ie a pair of open and closed parentheses) is a very common thing to do, Codea helpfully provides a shortcut. This is the third key from the left on the extra row of the keyboard. Touch that, and note that the cursor is between the parentheses - just where we want to type next, in fact.

The first two options are the x and y coordinates of the centre of the ellipse. The origin (0,0) of the coordinate system is actually at the bottom left of the screen, so if we put (0,0) here we'd get a circle in the corner. Instead, let's put it at the centre of the screen. This involves knowing how wide and high the screen is so that we can figure out the actual coordinates. Fortunately, we don't have to know this, only Codea does. We can use the magic words WIDTH and HEIGHT to find the centre of the screen. These are variables (though they shouldn't vary!) that Codea interprets as the number of pixels across and up the screen. They can be used in mathematical operations to specify coordinates on the screen by proportion. Thus (WIDTH/2,HEIGHT/2) is the centre of the screen. So type this into the code. It should now read ellipse(WIDTH/2,HEIGHT/2). Notice that as you type WIDTH then Codea suggests the word WIDTH. Indeed, this works even if you type width, which is quite useful. There's another useful key on the extra row here. The one next to the quotation commas looks like a load of mathematical symbols. It is. Touching this key brings up a new list of keys which can be used for, amongst other things, inserting mathematical symbols. This makes the / easier to find.

We're not quite done. We haven't said how big our circle should be. This is the third parameter. We specify the diameter of the circle. This is a good way to get a feel for how big the screen is. Try 100 as a first go. Your code should look like the following.

-- Use this function to perform your initial setup
function setup()
   print("Hello World!")
end

-- This function gets called once every frame
function draw()
    -- This sets a dark background color 
    background(40, 40, 50)

    -- This sets the line thickness
    strokeWidth(5)

    -- Do your drawing here
    ellipse(WIDTH/2, HEIGHT/2, 100)
end

Now press the "Run" arrow to see your code in action. With a bit of luck you should see the following picture.

Congratulations! You've written a program in Codea!

Making Changes

You can now play with the various parameters to get a sense of how things change and a feel for the screen size and dimensions. If you want an actual ellipse, add a fourth parameter to the list following the word ellipse in your code. Remember that the "BACK" key gets you back to your code. If you do something wrong (ie that Codea doesn't understand) it'll either tell you in the code, or in the window where "Hello World!" is still on display. The error messages might be a bit opaques at this stage, but hopefully the code that you have is simple enough that just knowing that there is an error is enough for you to find it.

The Extended Keyboard

There are two more useful keys on the extra row that are worth mentioning at this stage. These are the two in the middle, next to the "Maths" one. These move the cursor key one character to the left or right. This is very useful for getting around in your code as it can be tricky to get the cursor in the right place by touch alone.