Back to Beyond the Codea in-app reference

The Codea Editor

Introduction

When you open a new or existing Codea project, you are presented with the Codea Editor. What you will see will depend on your chosen theme and the orientation of your iPad. There are two available themes: Codea Light and Codea Dark. The Codea Editor supports both landscape and portrait orientations. Some of the features of the Codea Editor are documented under 'Editor Basics' in 'Getting Started' on the Codea Home Screen.

Below is an example of the Codea Dark theme in landscape orientation, and with the Search pane open too. The parts of the display are explained further below.

[a] The Editor pane

Initially, the Editor pane fills the whole of the display. In the top left corner of the display is a triangle pointing left (a close pane symbol) and in the bottom left corner is an 'X' symbol. Tap either to exit the Codea Editor and return to the Codea Home Screen. In the bottom right corner is a Play symbol. Tap it to start the execution of your code (see also [o] below).

When the on-screen keyboard is visible, the caret (the short vertical slowly-blinking blue line) marks the position where the next character will be entered when you tap a character key on the keyboard. As you make changes to your code, the changes are automatically saved. There are a number of ways to position or move the caret.

Tap the display to place the caret (see below) and open the on-screen keyboard. If you place the caret at a point that will be covered by the on-screen keyboard, the contents of the Editor pane will scroll up so that the relevant line appears immediately above the keyboard. The on-screen keyboard includes an additional row of special keys (see [e] to [o] below).

Tap on the Editor pane to reposition the caret. Use the special key to move it one character left or right (see [i] below). Swipe the Editor pane horizontally left or right to move it one character in that direction. Touch and hold on the Editor pane to show a magnification and to allow the caret to be placed with more precision (by dragging).

If the caret is placed at the end of a partially completed keyword that appears in Codea's autocomplete dictionary, possible autocomplete options will appear above the on-screen keyboard. An option can be selected by tapping it (see also [e] below).

Double-tap on a range of characters on the Editor pane to select a word. Double-tap on an empty part of the Editor pane to be given the option to Select, Select All or Paste. 'Select' selects the nearest whole word before the caret up to the caret and also selects any characters immediately following the caret. 'Select All' selects the whole contents of the current tab. 'Paste' pastes the current contents of the clipboard at the caret, or replaces the current selection with those contents.

The Editor makes use of syntax highlighting: green for Lua comments, red for string literals enclosed in quotation marks, purple for reserved Lua keywords, yellow for variables used by Lua to refer to functions (such as print or table.insert), blue for variables or indexes used by the Codea API to refer to functions (such as vec2) and orange for variables used by the Codea API to refer to other values (such as LANDSCAPE_ANY).

Touch and drag vertically on the Editor pane, or flick it, to scroll its contents up or down. Scrolling the contents up hides the names of tabs to create more space for your code. Scrolling the contents down to their start, or flicking the contents down, reveals the tab names again.

[b] The Main tab

Every Codea project has at least one tab named 'Main', which cannot be deleted or renamed.

[c] The '+' tab

Tap the '+' tab to show a pop-up that allows you to: (1) Create New Class; (2) Create Blank File; or (3) select or deselect Dependencies. Tap outside the pop-up to cancel it.

The 'Create New Class' or 'Create Blank File' buttons allow the creation of a new tab with a unique name. The name of a tab is made up of lower or uppercase letters (including accented letters) and numbers, but no spaces.

[d] Other tabs

Tap a tab in order to make it the current tab.

Touch and drag the current tab horizontally in order to change its order.

Touch and hold a tab (other than the 'Main' tab) in order to show a pop-up that allows you to: (1) Rename; or (2) Delete. Tap outside the pop-up to cancel it.

[e] The or (tab) key

The appearance and effect of the tab key depends on whether autocomplete options are presented above the on-screen keyboard. If they are, tapping the key selects the first autocomplete option.

Otherwise, the effect of the key depends on the location of the caret and whether characters are selected (see [x] below). If the caret is located at the beginning of a line, tap the key to inset a tab character at the location of the caret. Tab stops are located every four characters. Otherwise, tap the key to insert four space characters at the location of the caret.

If characters are selected, tap the key to insert a tab character at the start of each line including the selected characters. The whole of each line will then be selected.

[f] The (search) key

Tap the key to toggle on or off the Search pane to the left of the Editor pane. The example above shows the Search pane. If the Search pane is open, the key is highlighted.

[g] The (lookup) key

Tap the key to toggle on or off the Lookup pane to the left of the Editor pane, containing Codea's in-app reference. If the Lookup pane is open, the key is highlighted, unless the pane has been opened via a selection (see [j] below).

[h] The (math) key

Tap the key to open a pop-up with commonly-used math, logic and expression symbols. You can also touch and drag the key to select quickly a symbol.

[i] The (caret) key

Tap the left or right edge of the key to shift the caret (see [a] above) by one character.

Touch and drag the key to shift the caret around your code.

[j] The (select) key

Tap the left or right edge of the key to select one more character to the left or right.

Touch and drag the key to drag out a selection in your code. On completion you will be given the option to Cut, Copy, Paste or Lookup. 'Lookup' opens the Lookup pane (see [g] above).

[k] The or key

The effect of the key depends on whether one or more characters are selected (see [x] below).

Tap the key to insert a pair of round brackets ('()') at the position of the caret. The caret is then re-positioned between the brackets.

If one or more characters are selected, tap the key to surround the selection with round brackets. The caret is then positioned after the selection.

[l] The or key

The effect of the key depends on whether one or more characters are selected.

Tap the key to insert a pair of double quotation marks ('""') at the position of the caret. The caret is then re-positioned between the marks.

If one or more characters are selected, tap the key to surround the selection with double quotation marks. The caret is then positioned after the selection.

[m] The key

A common trait found in simulations and games is incrementing values over time. In some programming languages this is performed with a += operator. That is, a += b is shorthand for a = a + b. Lua does not provide this operator, however you can use the key to expand the currently typed symbol. This can be a time-saver when dealing with long variable names, such as self.position.

[n] The '=' key

Tap the '=' key to insert a '=' character at the position of the caret (or replace the current selection with a '=' character).

[o] The (Play) key

Tap the key to start the execution of your code.

[p] The Undo key

The on-screen keyboard can be toggled between letters and numbers and punctuation characters. The Undo key is included with the numbers and punctuation characters. Tap the key to undo recent changes.

[q] Additional keys

Touch and hold certain keys in order to show a pop-up with alternative keys. For example, touch and hold the right single quote (''') key in order to access the backtick character ('`').

[r] Additional keyboards

If additional keyboards have been enabled on your iPad (see 'Entering Emoji' below) touch the globe key to select those keyboards.

[s] The Search pane

Open the Search pane to search your code. What the pane shows depends on whether or not search text is entered at the top of the pane.

If no search text is entered, the pane shows a list, by tab, based on lines of code beginning with, or containing, the keyword function. Tap on an item in the list to jump to the line of code in the Editor pane.

Enter the text to be searched for at the top of the pane.

[t] Found text

The Search pane will list, by tab, snippets of code containing the found text, with that text highlighted. Tap a snippet to jump to the code in the Editor pane, with the found text selected.

[u] Cancel the Search pane

Tap the 'cancel' buttton at the top of the Search pane to clear the results of a search and close the on-screen keyboard.

[v] Close pane button

Tap the triangle pointing left at the top of the Editor pane to close the Search or Lookup panes.

[w] Line number column

Each line of code in each tab is numbered to identify it. Lines of code longer that the current width of the Editor pane will wrap to a second or third line. Lines beginning with the keyword function are highlighted with an orange 'f' symbol.

Tap the line number to select the line of code.

Touch and drag the line number to select lines of code.

[x] Selections

Selected text is highlighted and the start and end of the selection marked with 'lollipops'.

If it is not present, tap on a lollipop to be given the option to Cut, Copy, Paste or Lookup. 'Lookup' opens the lookup panel (see [g] above).

Touch and hold a lollipop to show a magnification and to allow the lollipop to be placed with more precision (by dragging).

Touch and drag a lollipop to increase or reduce a selection.

Entering Emoji

Emoji is the Japanese term for the picture characters or emoticons used in Japanese electronic messages and webpages. Emoji characters can be entered directly in the Codea Editor by first enabling the iPad's emoji keyboard. Instructions for doing so are published by Apple here.

Emoji characters are drawn in the Editor using the iOS built-in font AppleColorEmoji.

Emoji characters in Lua string literals in Codea are represented by their Unicode codes in the UTF-8 format.