Bounces User Interface

Project window overview

Lua code editor

Bounces includes a powerful Lua code editor supporting syntax highlighting, syntax errors detection, code-completion, auto-indentation, multiple panes…

Lua-syntax-related features

Feature	Description
Syntax highlighting	The Lua code editor implements advanced syntax highlighting capable of detecting the precise role of any syntax element in a Lua source file. For example, local variables, global variables and upvalues are presented with different colors, to help you detect mistyping errors at first sight. The syntax font and colors can be customized in Bounces preferences for both light and dark appearances.
Syntax-aware selection	Triple-click selects the Lua statement at the click location; if you maintain the mouse button pressed and move the mouse, the selection is extended so as to include entire statements and/or syntax blocks.
Variable usage visualization	Double-click on a variable highlights all uses of this variable, in accordance with Lua scoping rules. Read and write accesses to the variable are highlighted with separate colors, so the variable value changes can be easily detected. You can navigate between occurrences of a variable by pressing cmd alt G or cmd alt shift G (backward direction).
Variable renaming	alt double-click on a variable to rename evrey occurrence of this variable in its current scope. Variable renaming works for local variables, upvalues and global variables inside the current Lua source file.
Smart commenting	Comment the selection by pressing cmd - (or with the Comment Selection in the Syntax menu. If the selection empty, the line at the insertion point is commented. If the selection includes a comment, Lua nested comments syntax is used, so that the old comment is included in the new one. If the selection only include comments or is inside a comment, the command becomes Uncomment Selection and the outermost comment is removed.
Automatic indentation	Indentation is updated as you type the code. Press tab for indenting the current selection.
Syntax errors detection	Syntax errors are detected in real-time as you enter the code. An error is signaled by a red triangle error in front of the line where the error has been detected.

Auto-completion

The Bounces Lua editor supports auto-completion of many elements in the source code: auto-completion can be used on variable names, table and objects fields, methods, and also on Lua module names and resource names! Auto-completion is Objective-C-aware and supports completion of Objective-C methods and properties defined in the IOS SDK.

The auto-completion menu at the current insert position is shown when pressing the esc key on the keyboard.

Some examples may bring a better vision of scope of code completion in Bounces:

Completed entity	Example
Variable name
Object property
Lua module name/path
Resource name/path

The Lua code editor toolbar

Other Lua code editor features

Feature	Description
Zooming	If you use a trackpad, you can pinch-to-zoom in the Lua code editor. Use two-finger double-tap to restore the x1 zoom factor. Keyboard-based zooming is also available using cmd alt + and cmd alt -.
Editor splitting	Use the editor contextual menu or the View menu in the menu bar to split the current editor horizontally or vertically. Use the close button in an editor pane or select Close Pane in the editor contextual menu to remove a secondary editor pane.

Image and Quicklook viewers

The image viewer in Bounces provide a simple view of an image resource and an easy access to the available editors through the Edit menu in the viewer toolbar. In addition, it include a simple gesture-based zooming feature and display size and type information about the image.

The Quicklook viewer is similar and is used for non-image resources. It presents a Quicklook view of the resource nd an easy access to the available editors through the Edit menu in the viewer toolbar. As it uses Quicklook, its display can depend of the Quicklook plugins that you have installed in your system.

Project Files list

The Bounces Project Files List is divided in 3 sections:

• Source Files: the Lua source files and various resources of your Bounces project (running in one Lua Context),

• External Libs: the bindings libraries making the link between your Lua code and native libraries and frameworks linked with your application. Opening a bindings library in the list displays the Lua interface files for this library.

• Loaded Items: the list of all Lua source files and resources loaded on the connected target, in reverse chronological order (i.e. the most recent first).

Source Files hierarchy

Source files can be organized in Files Groups.

Files groups shall be included in the dot-separated item path when you require a Lua module or when you get a resource with getResource. For example, in the program presented above, you could write:

local TableCellClass = require("CheckerTableCell")

getResource("DetailViewNib", 'nib', self, "detailViewNib")
getResource("assets.tableItems", "plist", self, "model")
getResource("assets.image.orange", "public.image", self, "fruitImage")

Note: when requiring a Lua module from an external library, you can omit the library name from the path.

-- For example, you can write:
local UiView = require "UIKit.UIView"
-- or if you prefer:
local UiView = require "iOS.UIKit.UIView"

Files Indicators

Indicator	Description
Loaded	The source file has been loaded on the connected target (on a group, means that at least one item of this group has been loaded.
Auto-reload	Indicate that the Lua module will be automatically reloaded as soon as it changes.
Error	Indicates a syntax error in a Lua Module, or an error in the preprocessing of a resource file.
Needs reload	The Lua module has changed since last loaded on the target (and is not in auto-reload mode).
Linked file	This file (resource or Lua module is linked to an external file, and any change to this external file will be propagated to the application.
Read-only	The file can not be edited (usually set on Lua modules in an external lib, and on loaded items).

Files actions

Files list contextual menu

Source Files contextual menu

Loaded Items contextual menu

Linked source files

By default, when you drag a file to your Bounces project, Bounces keeps a link to this file's location in the file system and monitor this location, so that any change to the original file will be visible in the Bounces project and propagated to the target application, if a target application is connected. In Bounces files list, a source file with such a link to an external file location is represented with a linked file indicator on top of the file's icon.

A source file with no linked file indicator is local to the Bounces project, meaning that it is stored inside the corresponding Bounces project document. Editing a local source file with an external editor is of course possible, and won't have any side effects on other files in your file system.

Choosing to work more with local or with linked source files in Bounces is a matter of personal preferences for your workflow. And you can change the linked-file-status of a source file in Bounces at any time with the Link to File contextual menu commands, or create a new link by dragging a file from the Finder onto an existing source file of your Bounces project.

Loaded items history

When your Bounces project is connected to a target application, you can view in the LOADED ITEMS group the whole loaded-items history since this target application started. This history contains both loaded Lua modules and loaded resources. It is ordered chronologically, with the oldest loaded item at the bottom of the list and the most recently loaded at the top.

You can not edit a loaded item, but could can visualize it by selecting it in the list. The contextual menu on a loaded item allows you to jump to the original source file from which this items was loaded (if it still exists in the current SOURCE FILES group) and to restore the original source file with the content of the loaded item.

On the other side, in the SOURCE FILES group, if a project source file has its loaded indicator displayed, you have a direct access from its contextual menu to all loaded as versions of this source file, since the target application started. The Revert to Loaded Version submenu shows the preview and loading time of all loaded versions for the source file and enables you to restore any of them.

Execution control

Bounces execution control tools are located in the project window toolbar.

Variables Inspector

The variable inspector in Bounces let you inspect the whole state of your Lua program in the selected target execution context: this includes global variables as well as Lua threads with their stack frames and associated local variables.

The variables inspector displays visual symbols to make variables inspection more intuitive. These symbols provide direct information about the roles and types of the presented variables or values, as listed in the table below:

Possible Actions	Description
Display the source code corresponding to a Lua function call	Click on this function call in the call stack.
View the fields of a table, struct or object	Unfold the table / struct / object structure by clicking on the corresponding triangle. Native object properties are hidden by default, but you can select a subset of native properties to be inspected on a per-class basis (like the UIViewController properties highlighted in the above screenshot).
Inspect global variables	Open the Globals group located below Lua threads in the inspector
Inspect Bounces libraries / Lua standard libraries	Open the corresponding group at the bottom of the variable inspector. Inspecting the Bounces Library group can be useful to get information about Lua classes declared in the current project and about native classes and structs referenced by the project. Inspecting a native class is also an easy way to visualize the enum types associated with this class.
Change the value of a variable	Click on the value and enter the new value. Editing a value can be done on number, strings and boolean values. It will not change the type of the value.
Change the value of a table or object field	Same as for changing the value of a variable: Click on the value and enter the new value. Editing a value can be done on number, strings and boolean values. It will not change the type of the value.
View the definition of a Lua function value	Click on the Lua function value.
View a variable in the code	Click on the name of a function parameter or local variable or up-value in the variable inspector, and this variable will be highlighted in the code editor.
Display/Hide up-values	Click on the symbol next to a stack-frame function name to toggle the display of up-values in this stack-frame.
Display/Hide masked variables	Click on the symbol next to a stack-frame function name to toggle the display of masked local variables in this stack-frame.

Note: Global variables and Standard Libraries can be inspected while the program is running; threads callstacks can only be inspected when the program is paused.

Adding native object properties to the variable inspector

The variable inspector displays a selected set of native properties on a per-class basis.

To add a native object property to the inspector, follow these steps:

1. Display the Lua interface file for the native class in the class inspector.
   To make this step easier, you can right-click on a class type in the variable inspector to display the class hierarchy for the current object. Selecting a class in this menu shows the corresponding Lua interface in the code editor.
   

2. Find the property definition in the Lua interface file and use the contextual menu to start inspecting this property.
   

3. The property is immediately added to every instance deriving of the native class in the variable inspector.
   

To stop inspecting a native property, follow the same steps. The contextual menu in the Lua interface file will now propose Stop Inspecting Property….

Lua Console

The Lua console displays events coming from the selected target Lua execution context. It also includes a Lua command editor that allows to execute Lua code in the current target execution context.

Lua command editor

The command editor has the same level of functionality as the main Lua source editor and it supports multilines Lua code snippets.

Lua commands are executed in the context of the selected stack frame if the execution context is paused (e.g. stopped on a breakpoint). As such, a Lua command has access to any local variable or up-value visible from the selected stack frame code location.

If the execution context is running (i.e. not paused), you can still execute Lua commands, that have access to the execution context's global variables, including a full access to the target application native bridge. In such case, a Lua command is executed in parallel with other Lua threads running in the execution context.

You run a command by typing cmd return in the command editor or by clicking on the execute command button. You can recall previous commands with the command history stepper.

Lua console output

The Lua console output displays events coming from the selected target Lua execution context: loaded Lua modules, loaded resources, text messages printed by the Lua print() function, and runtime errors.

The Lua console output keeps rich information about incoming events. Using the console contextual menu, you can:

• filter console events by kind(s),
• hide messages before a certain date (useful if the Lua program is print-intensive),
• hide or show the event timestamps,
• do specific actions on some types of events: show the location of a runtime error in the main Lua editor, display a specific loaded Lua module or resource version…

Bounces Menus reference

Program menu

Syntax menu

Execute menu