Code editor

The code editor is where you write your programs. It edits the project's .aru files, each one in a tab, with colors, autocompletion, hints and jumps to definitions. It also opens the project's text files (.md and .txt, such as README.md), but as plain text: no colors and no help.

There are several ways to open it:

• Double-click a code or text file in the explorer. If it is already open, the editor switches to its tab.
• Home › View › Code, on the ribbon: it shows the editor.
• Open File and New File, on its own bar (see "Tools").
• From the windows that take you to a line: the error list, the Task List and the debugger open the file at the right place.

A walkthrough

Writing with help, jumping to a function and coming back.

1. Open the file. In the explorer, double-click your main file, inside Code. It opens in a tab with its name.
2. Write with autocompletion. Type Disp and press Ctrl+Space. If there is only one suggestion, Display, the editor writes it; if there are more, the list shows up: pick one with the arrow keys and press Enter. Type a dot and press Ctrl+Space again: now the list shows what the Display module has.
3. Look at the parameters. Type open(. A hint with the parameters of Display.open shows up above the line, with the one you are typing highlighted.
4. Jump to a definition. Hold Ctrl and move the mouse over the name of one of your functions, where you call it: it gets underlined and the pointer turns into a hand. Click: the editor jumps to the line where you declare it, even if it is in another file of the project.
5. Come back. Press the back arrow, the first one on the bar, until you are back where you were.
6. Tidy up the code. Press Code Beautifier: it sets the indentation and the spacing of the whole file. Ctrl+Z undoes it.
7. Save with Ctrl+S. While there are unsaved changes, the tab shows an asterisk (*) after the name. Then compile with Build › Compile.

Tools

The bar

The buttons on the bar have no text: hover over them to see their names.

Button	What it does	Key
The two arrows	Back and forward: they take you to the places you have been (see "Moving around the code").
Open File	Opens a .aru file and adds it to the project if it was not there. If it is not in the project's Code folder, it copies it there first.
New File	Asks for a name, creates the file in Code (adding .aru if the name lacks it) and opens it.
Save File	Saves the active tab.	Ctrl+S
Find & Replace	Opens the search panel.	Ctrl+F
Code Beautifier	Tidies up the code: indentation, spacing and blank lines.
Close Tab	Closes the active tab. If it has unsaved changes, it asks first.

On the right of the bar is Search symbols..., the symbol search.

The File and Edit menus

Above the bar, File and Edit open two menus:

• File: New, Open, Save and Close. They do the same as New File, Open File, Save File and Close Tab.
• Edit: Find, Copy, Cut, Paste, Select All and Font. Find and Font do nothing (see Known issues).

The right-click menu

A right click on the text opens Find, Cut, Copy, Paste, Select all, Add Watch and Font.

• Add Watch adds the variable at the cursor, or what you have selected, to the Watch window. If Watch is closed, it opens it. The debugger tells you more.
• The right click does not move the cursor: Add Watch takes the word where the cursor is, not the one under the mouse. Click on the variable with the left button first.
• Find and Font do nothing.

Writing code

Tabs, colors and gutter

• Each open file has a tab with its name. Drag a tab to move it.
• The colors tell apart keywords, strings, numbers, comments and module names (in bold). Parentheses, brackets and braces change color with their nesting depth.
• With the cursor next to a parenthesis, both it and its pair are highlighted.
• If you leave the cursor for a second on a word that appears more than once, every place where it appears gets a frame.
• The line numbers go on the left; the one of the cursor line is brighter. Next to them, a yellow bar marks the lines you have changed and not saved, and a green one, the changed lines that are already saved.
• The - and + buttons in the gutter fold and unfold blocks: functions, classes, if, loops… Also with the keyboard: Alt+Shift+1 folds them all; Alt+Shift+2 to Alt+Shift+9 fold the ones at that nesting level or deeper, and Alt+Shift+0 unfolds them all.
• A click on the left edge of the gutter sets or removes a breakpoint. The debugger tells you more.
• At the bottom, the status bar shows the line and column of the cursor, and the path of the file.

Errors while you type

Shortly after you stop typing (half a second; up to a second and a half in long files), the IDE checks the code. It underlines errors with a red wavy line and warnings with an orange one, and marks their lines in red on the minimap. The full list is in the Error List window, which Home › View › Errors opens (see The interface).

Automatic indentation and the Beautifier

When you press Enter, the new line gets the indentation of its block: 4 spaces per level. When you type end, else, elsif, elfor, catch, until or default alone on its line, the line goes back one level.

Code Beautifier tidies up the whole file or, if some text is selected, only the selected lines:

• the indentation, with 4 spaces per level;
• the spacing: one space around operators and = and one after each comma, and none inside parentheses and brackets;
• blank lines: at most one in a row, one before and one after each function, method, class, struct or enum (without separating them from the comment right above them), and none at the end of the file;
• quotes: strings in single quotes become double-quoted, except the ones that contain a double quote.

Ctrl+Z undoes the whole change at once. If the file has syntax errors, even outside the selection, it changes nothing and shows a message.

Synchronized editing

Select a piece of code and press Ctrl+J: the names that appear more than once in the selection get marked. Change one and all the identical ones change at the same time. Tab and Shift+Tab move to the next and the previous one; Esc ends it.

The font and zoom

The font is Consolas, at 10 points. With the editor active (click on the text), Ctrl + mouse wheel makes it bigger or smaller, from 6 to 72 points. Each tab keeps its own size, and a newly opened one starts at 10 again.

Autocompletion

Ctrl+Space opens the list of suggestions. It does not pop up by itself while you type: you open it.

• It filters with what you have typed of the word. Any part of the name works, regardless of case: ex finds imgPlayerExplosion.
• If only one suggestion is left, it writes it without opening the list. If none is left, it does nothing.
• Each row shows what it is (Variable, Function, Class, Module…), the name, the parameters and the description.

With the list open, keep typing to filter further (Backspace removes letters from the filter). The arrow keys, PgUp, PgDn, Home and End move through it; Enter or a double click write the chosen one, and Esc closes it.

With no dot before it, the list brings what is visible from the cursor:

• the variables and parameters of the function you are in, and what the file declares: variables, constants, functions, classes, structs and enums;
• what the files you bring in with import declare, and the files they import;
• the modules (Display, Sound…), the standard functions (println, clock, random…), the constants (PI, HIGH, the ERR_… codes) and the keywords.

The variables and what is closest to the cursor come first, and the keywords last.

After a dot, it brings what the thing on the left has:

• a module: its functions, properties, constants and submodules. Display. offers open, update, fps, draw…;
• a variable, if the IDE knows its type from what you assign to it:
  • of a class, its methods and properties, inherited ones too, and the methods every object has;
  • of a struct, its fields, plus copy and clone;
  • of an enum, its values;
  • a string, a list or a map, their methods;
  • what a module returns, such as a sprite from Sprite.load, its methods and properties;
• a chain of dots: in player.weapon. it follows the type of each field.

struct Point
    var x = 0
    var y = 0
end

var p = Point(3, 4)
println(p.x)   // 3

Type p. and press Ctrl+Space: the list offers x and y, plus copy and clone. Structs are explained in Structs.

Hints

On mouse hover

Leave the mouse still over a name and, in less than half a second, a hint shows up with what the IDE knows about it:

• what it is (func, method, class, module, property, const…) and its name;
• its parameters. If there are several versions of the same function, one per line; for a class, how to create it (the parameters of its init);
• its description: the one from the module help, or the one you give it in a comment (see "Document your code", below);
• for a variable or a constant, its type and the value the code gives it;
• where it is declared: in which class, in which module, or Project function if it is one of your functions.

The hint goes away when you move the mouse, click, move the cursor or press Esc. It only shows up in code files.

The parameters of a call

With the cursor inside the parentheses of a call, a hint shows up above it with the function and its parameters, with the one you are typing highlighted. If the function has several versions, they all show up, one per line, with the matching one highlighted. It also works when you create an object: Enemy( shows the parameters of the class's init. Esc closes it.

Document your code

Your comments show up in the hints and in autocompletion:

• A comment right above a function (func), a method (def), a class, an enum or a constant, with no blank line in between, is its description. If there are several comment lines in a row, they all go in.
• A comment at the end of the line of a variable, a constant or a this.field = … is the description of that variable.
• Inside the comment, the lines that start with @param, @return, @note, @example or @see show up apart, below the description.

// Adds two numbers.
// @param a the first one
// @param b the second one
// @return the sum of both
func add(a, b)
    return a + b
end

var lives = 3   // The lives the player has left

println(add(lives, 2))   // 5

Moving around the code

Go to definition

Hold Ctrl and move the mouse over a name: if the IDE knows where it is declared, it underlines it and the pointer turns into a hand. Click and the editor jumps there: a function, a method, a class, a variable or a constant, in the same file or in another file of the project, which it opens if it was not open.

Back and forward

The two arrows on the bar go through the places the editor records, as in a web browser. The back one goes to the previous place, even in another file, and the forward one undoes the step back. They are disabled when there is nowhere to go.

The editor records a place every time you jump: with Ctrl + click, with the symbol search or the search panel, when you switch tabs or open a file, when you go to a line from the error list or the Task List, and when the cursor moves 20 lines or more away from the last recorded place. It keeps the last 100.

Symbol search

Search symbols..., on the right of the bar, searches the active file for its classes ([C]), its methods ([M], as Class.method) and its functions ([F]), in alphabetical order.

• Click the box: the whole list shows up. Type to filter it; any part of the name works, regardless of case.
• Pick one with the arrow keys and press Enter, or click it: the editor goes to its line and centers it.
• Esc closes the list.

Minimap

On the right of each tab, the minimap shows the whole file in small, with its colors. A box marks the part you see in the editor; a green line, the cursor line; red lines, the lines with errors, and yellow ones, the lines with breakpoints.

• A click takes the editor to that line and centers it.
• Dragging with the button held scrolls the text.
• The mouse wheel over the minimap scrolls the editor.
• Ctrl+Shift+M hides or shows it, in the active tab.

Find and replace

Ctrl+F, or Find & Replace on the bar, opens the search panel at the top right of the text. It comes with what you have selected or, if nothing is, the name at the cursor with its dots (Display.draw, for example).

• It searches as you type, from where the cursor was when you opened the panel; at the end it goes on from the start. What it finds is selected in the text.
• If there is nothing, the search text turns red.
• The counter shows which match is selected and how many there are in the file: 2/5. If none is selected, the first number is 0.
• < and > go to the previous and the next one, and wrap around at either end.
• Aa matches case, and W only finds whole words. A click turns them on and off, and they count from the next search: after changing them, press >.
• Clear, the x inside the box, empties it.
• X closes the panel. To make it wider, drag its left edge.

It searches for the text as it is: there are no regular expressions.

Replace

▼, on the left of the panel, shows the replace row, and ▲ hides it. Type the new text in its box: it comes with "Replace..." written in it, which a click does not clear, so delete it first.

• R (Replace next) changes the selected match and jumps to the next one. If none is selected, it only jumps.
• All changes them all in the file, from start to end, and tells you how many it changed. Ctrl+Z undoes them all at once.

Both take Aa and W into account.

Explorer resources

Drag a file from the explorer onto the editor and drop it where you want the code: the editor writes what it takes to use it.

You drop	It writes
A code file	import "Utils.aru", with its path inside Code, and a line break.
A sprite (.spr)	Sprite.load("Sprites/Hero.spr")
An image	A menu: Insert as Bitmap.load writes Bitmap.load("Images/Background.bmp"), and Insert as Path, just the path: "Images/Background.bmp".
A tilemap (.map)	A menu: Load tiles map writes GridMap.load("Maps/Level1_tiles.gmap"), and Load cells map, the same with _cells.gmap.
A song	A menu: Insert as Sound.loadMusic writes Sound.loadMusic("Music/Theme.jmu"); Insert as Path, just the path, and Insert as load + play, the code below.

Insert as load + play writes this, with the indentation of the line where you drop it:

if (Sound.loadMusic("Music/Theme.jmu")) then
    Sound.playMusic(true)
end

The paths are those of what the IDE exports when it compiles: images, as .bmp; tilemaps, as their .gmap files, and songs, as .jmu. An image only reaches the game with Include in Build turned on in the image editor. The rest is explained in the tilemap editor, the sprite editor and the Bitmap, GridMap and Sound pages.

Task List

Home › View › Task List opens the Tasks Manager window: the comments in the project that note something to do.

A comment goes into the list if it has one of these tags, in capitals and as a separate word: TODO, FIXME, BUG, WARNING, HACK, OPTIMIZE, REFACTOR, TEMP or NOTE. What follows it (without the colon) is the text of the task. If a comment has two tags, the most serious one counts.

// TODO: make the boss shoot diagonally
// FIXME the score is not cleared on restart
var level = 1

• The nine buttons at the top are filters, one per tag: a click turns its own on or off. When the window opens, only the TODO one is on. Hover over a button to see which one it is.
• The tasks are grouped by file, each with its tag, its line and its text, the most serious first: FIXME, BUG, WARNING, HACK, OPTIMIZE, REFACTOR, TEMP, NOTE and TODO. With the code above at the start of a file and the FIXME and TODO filters on, you get [FIXME] Line 2: the score is not cleared on restart and [TODO] Line 1: make the boss shoot diagonally.
• Double-click a task: it opens the file at that line. On a file: it opens it.
• At the bottom it shows how many there are of each tag, and the total, including the ones the filters hide.
• The list does not update by itself: Refresh reads the files again. It reads what is saved on disk: save what you have just typed first.

What it saves

• Save File, Ctrl+S and File › Save save the active tab to its file and remove the asterisk.
• Home › Project › Save, on the ribbon, saves every tab with changes, plus the other editors and the project.
• Close Tab asks before closing a tab with changes: Yes saves it, No throws the changes away and Cancel leaves it open.

Save before compiling

Compile, Run and Debug compile the files as they are on disk: they do not save the editor. What you have not saved does not reach the program, and Run does not notice that the code has changed. Save first with Ctrl+S or with Home › Project › Save.

Shortcuts

They work with the cursor in the code editor.

Shortcut	What it does
Ctrl+Space	Opens autocompletion.
Ctrl+F	Opens the search panel.
Ctrl+S	Saves the active tab.
Ctrl + click	Goes to the definition of the name.
Ctrl + wheel	Makes the font bigger or smaller.
Ctrl+Shift+M	Shows or hides the minimap.
Ctrl+J	With text selected, starts synchronized editing.
Esc	Closes autocompletion and the hints, and ends synchronized editing.
Alt+Shift+1	Folds every block.
Alt+Shift+2 … Alt+Shift+9	Fold the blocks at that nesting level or deeper.
Alt+Shift+0	Unfolds every block.
F9	Sets or removes the breakpoint on the cursor line.
F5	Compiles and debugs (Debug); with the program paused, goes on (Continue).
F10	Step Over.

The ones for typing and moving through the text are the usual ones, with two that do something else in other programs: Ctrl+Y and Ctrl+N.

Shortcut	What it does
Ctrl+Z and Ctrl+Shift+Z	Undo and redo. Also Alt+Backspace and Alt+Shift+Backspace.
Ctrl+C, Ctrl+X and Ctrl+V	Copy, cut and paste. Also Ctrl+Insert, Shift+Delete and Shift+Insert.
Ctrl+A	Selects everything.
Ctrl+I and Ctrl+U	Add and remove indentation on the selected lines.
Ctrl+Y	Deletes the whole line (it does not redo).
Ctrl+Shift+Y	Deletes from the cursor to the end of the line.
Ctrl+N	Inserts a blank line (it does not create a file).
Ctrl+Backspace and Ctrl+T	Delete from the cursor to the start and to the end of the word.
Ctrl+← and Ctrl+→	Jump from word to word.
Ctrl+Home and Ctrl+End	Go to the start and the end of the file.
Ctrl+↑ and Ctrl+↓	Scroll the text one line.
Alt+Shift + arrow keys	Select a column.
Insert	Switches between insert and overwrite.

Known issues

• Find and Font do nothing. Neither in the right-click menu nor in the Edit menu. To search, use Ctrl+F or Find & Replace; to change the font size, Ctrl + wheel.
• The search and replace boxes do not clear. When empty, they show "Search..." and "Replace...", and a click on them does not clear that text: delete it before typing. If you leave the replace box empty and click somewhere else, it shows "Replace..." again, and R and All replace with that text. To replace with nothing, empty the box and press R or All without clicking anywhere else. If it has already happened, Ctrl+Z undoes it.
• Back does not always take you right back to where you were. After a short jump, less than 20 lines away in the same file, the back arrow skips the place you left from: the forward one takes you back to it. And after a jump to another file, it sometimes stops first at another place in that file (where your cursor was, or its start): press it again.
• The All hint says "Replaze all".

All the known issues of JARU, together, are in Known issues.