Tutorial 1 - Getting Started (Updated 30/08/15)

Comic courtesy of Ethanol & Entropy

0.0 Version Information

This tutorial has been updated for Codea version 2.3.1(47) on the 30th August 2015. You can check your version of Codea by tapping on the Two Lives Left logo in the bottom middle of the Codea start screen (Figure 1).

1.0 Getting Started

To start you need to purchase the Codea App and load it on your iPad. I'm using an iPad Air 16GB (model number A1475. The model number is written in tiny silver writing on the back of the iPad - you can identify your model using this site: https://support.apple.com/en-au/HT201471), so any of the later editions should just be quicker and shinier. The current version of Codea requires iOS 7.0 so any iPad which can run at least that will work.

You can get the App from iTunes here or just search for Codea in the App store. At time of writing the current version was 2.3.1. Codea uses the Lua programming/scripting language so throughout these tutorials I will use the two terms interchangeably depending on the context.

Tapping on the icon should bring up the start up screen shown in Figure 1. Scrolling up will reveal more example projects which demonstrate the functionality of Codea.

Figure 1. Codea Start Screen

1.1 Your First Program - Hello World

Sample projects are at the bottom (you can scroll these up and down) and your projects and the add a new project button is at the top. Tap on the Add New Project button and a dialog box will open up asking you for the project name (see Figure 2). Tap on the Text box and the screen keyboard will appear. Type Hello World and then tap the Create button.

Figure 2. New Project Screen

Codea will generate your Main class for you and display the code edit window (Figure 3). The first tab is always called Main. If you add more files to the program they get listed as a separate tab at the top of the code editor.

Figure 3. Code Edit Screen

So what is going on here? Well as the comic at the top says, it is traditional to start off with a Hello World program so the basic add Project template does all the work for you. If you have a short attention span then tap on the right arrow in the bottom right corner to go to the run program screen. You should see "Hello World!" printed in the box titled Output and a dark screen (Figure 4). Tap the back arrow in the bottom left to go back to the edit code screen (the other controls on this screen will be described later).

Figure 4. Codea Run Screen

Let's dig into what is happening in the code. The main class contains two functions and a bunch of comments.

1.2 Comments

Comments have no effect on your code, they are there to remind you what the code does. It may seem like a waste of time but try and comment as you write your code. Trying to retrospectively work out what a complex function does years later is no fun. It also makes it harder for someone else to work on or maintain your code. As with lots of things related to coding, everyone has an opinion on comments and whether they are necessary. Some argue they are a waste of time and your code should self document through the use of descriptive variable names and functions. This sounds like a good idea, but my experience is that nothing saves time like a few well placed comments when you come back in a years time to update your app.

A comment starts anywhere with a double hyphen (--) and runs until the end of the line. Lua also offers block comments, which start with --[[ and run until the corresponding ]]. 

Sidebar: Colours indicate the following in Codea:

Purple - function start and end
Red - a string
Green - a comment

1.3 Functions

Your program can contain any number of functions. Functions are interesting. In Lua, a function is a value with the same rights as conventional values like numbers and strings. Functions can be stored in variables (both global and local) and in tables, they can be passed as arguments, and can be returned by other functions. You can have Functions with or without arguments and they may or may not return a value (or multiple values). Functions written in Lua return multiple results by listing them all after the return keyword. We will see some examples of this in due course.

Sidebar: Swift and Objective C

For many years if you wanted to write Apps for the iPhone/iPad or Mac then you needed to learn Objective C. Objective C is a programming language (a bit like Lua) based on one of the most popular languages ever - C. Apple has recently released a new language called Swift which will eventually replace Objective C. Interestingly Swift incorporates a number of features which Lua already has (e.g. functions returning multiple values). The problem as a developer is learning all these languages which each have their own idiosyncrasies. If you want to program for Android then you need to learn another language called Java (also based on C).

When you start a new program, Codea will automatically add two functions:

1. setup() - which is called once to provide your initial setup. It is called before draw(); and
2. draw() - which is called once every frame. Codea tries to call the draw function 60 times per second (i.e. every 16.67 mS). If your program is doing something complex it may not be able to do this, and if so will call it as quickly as possible, dropping frames if required.

Sidebar - Note that the complete Codea reference documentation is available here if you want to explore any area in more detail. 

1.3.1 setup()

Looking firstly at setup(), this function only has one line of code: 

print("Hello World!")

Lua's print command automatically adds the newline for you, much like Java's println function. For those coming from Objective C you may note the missing semicolon at the end of the line. These are optional in Lua and the convention is to leave them off. Note that print() outputs to the "console" not to the main drawing screen. As we saw earlier in the program run screen, the Output box contains the console output. This means that print() is useful for some situations but not others. At the end of this tutorial we will show how to output "Hello World!" to the drawing screen.

1.3.2 draw()

The draw() function contains two lines (plus some comments).

background(40, 40, 50)

Background sets the colour of the drawing screen background (not the console/output screen). The 3 numbers represent the red, green and blue components of the final colour. Each component can vary between 0 and 255. You can also optionally assign an alpha channel, greyscale value or colour value using this function.

One of the funky things about Codea can be demonstrated here. Tap on the numbers in background and a colour selector wheel will pop up. you can use this to choose the exact colour that you want. Give this a try and then run your program again (tap the right arrow in the bottom right corner).

strokeWidth(5) 

StrokeWidth sets the thickness of lines (however we don't draw any lines in this example so you could delete this line of code).

Sidebar - As you work through these tutorials you will create a number of projects that you won't want to keep. To delete a project, tap and hold on the project in the launch screen to see the popup delete option (you can also copy, export or duplicate a program from here).

Now you might think that you could optimise the speed of the code (not that it needs it) by moving the background() statement from the draw() function to setup(), however this will only change the background once and next frame it will change back to the default value (black).

1.4 Drawing Text - text(string, x, y)

So how do you stick some text in the draw screen? Well there is a function for that! Type the following code into your draw() function and give it a go (Figure 5). 

Figure 5. Hello World using text function.

The statements should be self explanatory and as you type Codea will tell you what the function does and what parameters it expects.

background(40, 40, 50)
font("Georgia")
fill(255)               - - This will set the text colour white
fontSize(20)
textWrapWidth(70)
text("Hello World!", WIDTH/2, HEIGHT/2)

The text() function draws the nominated string, centred at the x and y co-ordinates provided.

Once again, tap on the play button (bottom right of the code editor screen) and if you see something similar to Figure 6, then you have completed Tutorial 1. Try playing around with different font sizes, comment out textWrapWidth and see what effect that has.

Figure 6. Hello World Run Screen.