Bounces User Interface

This document is a quick reference of the Bounces user interface. It may be worth reading if you get started with Bounces. You can also read it as a guided tour of Bounces.

Project window overview

Bounces project window

Lua code editor

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

Bounces Lua code editor

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). Bounces Lua code editor - variable usage
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. Bounces Lua code editor - error detection


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 Bounces code completion: variable
Object property Bounces code completion: property
Lua module name/path Bounces code completion: module name
Resource name/path Bounces code completion: resource path

The Lua code editor toolbar

Bounces Lua code editor toolbar
Toolbar element Description
Navigation arrows Use them to browse quickly your source files navigation history.
Alternatively you can use horizontal swipe gestures on your trackpad or magic mouse for more natural source files history browsing.
Source File path and type Informative. Display the source file logical path (i.e. the path that you would use in require or getResource) and type of the currently displayed source file. Present for all types of source files.
Functions menu A menu listing all functions, methods and properties defined in the current Lua module. Select a function to jump to its definition.
Globals menu A menu listing all Lua global variables used by the current Lua module.
This menu helps you to quickly identify the globals that your module reads or overwrites, and to check that you haven't by mistake referenced/created a new Lua global by misspelling a variable in your module.
Dependencies menu A menu listing recursively all external types and Lua modules referenced by the current Lua source file. Use the menu to jump to the definition of a referenced type or Lua module; use the navigation arrows or the swipe gesture to come back to the current module.
Reload module button Use this button to force the reload of the current Lua module on the selected target. Most of the time, this is equivalent to selecting the Load Source File command in the Execute menu.
However if the current Lua module hasn't changed since the last loaded version, the reload button will force a reload, where the Load Source File command is simply disabled.

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. Bounces Multiple Lua code editors

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.

Bounces Image viewer

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).

Bounces project files list

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("", "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
File Loaded indicator
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.
File Auto-reload indicator
Indicate that the Lua module will be automatically reloaded as soon as it changes.
File Error indicator
Indicates a syntax error in a Lua Module, or an error in the preprocessing of a resource file.
File needs reload indicator
Needs reload
The Lua module has changed since last loaded on the target (and is not in auto-reload mode).
File linked indicator
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.
File read-only indicator
The file can not be edited (usually set on Lua modules in an external lib, and on loaded items).

Files actions

Action How
Create a Lua Module Use the Add Source toolbar button, or do menu command New Lua File in contextual menu or Program menu.
Create a Files Group Use the Add Source toolbar button, or do menu command New Group in contextual menu or Program menu.
Rename a source file Select the file in the list and click on its name in the source file list or press Enter.
Add a source file Drag and drop the corresponding data or URL from the Finder or any other application, using key modifiers to select between keeping the added source file linked with the dragged file or not.
Or choose Add File... from the contextual menu.
Replace a source file's content Drag and drop a file from an other application onto an existing type-compatible source file. Use key modifiers to select whether the new source content shall be linked with the dragged file or not.
Delete source file(s) Select the files to delete and press the Backspace key or choose Delete Selected Items in the Program menu.
Edit/View a file in Bounces internal source editor Delect the file in the list
Edit/View a file in the default external editor Double-click on the file in the list or select the file and press return.
Note: you can define a default external editor for Lua source files in Bounces preferences.
Edit/View a file in a specific external editor Use the contextual menu command Open with and select the external editor from the list.
Link a source file to an external file Right-click on the source file and use the contextual menu Link to File
Remove the link to an external file Right-click on the source file and use the contextual menu Link to File
Reorder / move source files Use drag and drop to reorder or duplicate files inside the SOURCE FILES group.
Use a loaded item as a source file Drag the loaded item into the SOURCE FILES group.
Set the content of a source file to mach a loaded item Drag this loaded item over the source file.

Files list contextual menu

Source Files contextual menu

Source Files Contextual Menu

Loaded Items contextual menu

Loaded Items Contextual Menu
Action Description
View Original Source File Selects the original file for this loaded item in the SOURCE FILES group.
Revert Original Source File Sets the content of the loaded item's original source file to the loaded item's content

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.

Link to File command Description
Existing File... Links the Bounces source file to the selected type-compatible file location. The Bounces source file is set with the content of the external file.
New File... Saves the content of the Bounces source file into the selected location and keeps the link to this location.
Remove Link Removes the currently existing link and turns the Bounces source file into a project-local file.

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.

Loaded Items Contextual Menu
Action Description
View Original Source File selects the original file for this loaded item in the SOURCE FILES group.
Revert Original Source File sets the content of the loaded item's original source file to the loaded item's content

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.

Revert to Loaded Version Contextual Menu

Execution control

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

Bounces execution tools
Tool Description
ExecutionContexts List of currently-executing targets for this Project. Execution targets can run on a simulator or on a real device.
The colored circle next to a target represents the target's current activity with different color codes: blinking green when Lua code is executed on the target; blue when execution is interrupted on a breakpoint or error; grey when the Lua execution context is idle.
Select an execution context for displaying the current Lua debug state of the corresponding target.
Execution and debug commands are always executed on the selected execution context.
Debug tools The classic debugger commands: pause/continue, step over, step into, step out and abort execution.
Abort execution abruptly exits all functions in the stack of the current Lua thread and returns nil to the native caller if any.
All debugger command have keyboard shortcuts and are accessible from the Execution menu.
Breakpoints button Activate / deactivates breakpoints on the selected target.
Halt on error button Activate / deactivates halt on error on the selected target.
When halt on error is deactivated, errors are only signaled by a message in the Lua console; otherwise the execution stops on the instruction causing the error.

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.

Bounces variables inspector

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:

Bounces variables inspector type icons
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.
Inspecting class-related enums
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 up-value button symbol 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 masked variables button symbol 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.
    Class hierarchy menu in the variable inspector

  2. Find the property definition in the Lua interface file and use the contextual menu to start inspecting this property.
    Adding a native property to the variable inspector

  3. The property is immediately added to every instance deriving of the native class in the variable inspector.
    Displayed native property 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.

Bounces Lua Console

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

Bounces Program menu
Command Description
New Lua File Create a new Lua file in the project.
New Group Create a new Group in the project files list.
Add File Item... Add an existing file to the project, keeping the link to the selected file.
Add External Library Adds a Lua bindings library to the project, eventually replacing an external library with the same name.
Delete Selected Items Remove the selected items in the project files list from the project, leaving any externally linked file untouched.
Select Associated Xcode Project... Display the associated Xcode project selection dialog.
Open Xcode Project Open the associated Xcode project in Xcode.
Update Xcode Project Force an immediate update of the associated Xcode project to make it match the current Bounces project state.
Show Xcode Project In Finder Shows the associated Xcode project file in a Finder window.
Clear Association with Xcode Project Forget the currently associated Xcode project and don't update it anymore in the future.
Export Program... Create a .luapkg file containing every Lua source files and resources in the Bounces project for embedding in an application bundle. If an associated Xcode project is defined, the .luapkg file is added to the corresponding Xcode application target.

Syntax menu

Bounces Syntax menu
Command Description
Indent Selection Re-indent the selected Lua code in the currently edited Lua module.
Comment Line / Selection Comment the Lua code at the current line / the currently selected Lua code.
Uncomment Selection / Line Uncomment the enclosing comment of the current selection or insertion point.
Protect Selection Wraps the selected code in a call to Lua standard pcall function. Then if a Lua error occurs in the protected code block, the execution will simply jump out of the protected block.
Select Next Variable Reference When you have highlighted all references to a Lua variable by double-clicking on it, this command navigates to the next reference to this variable in the current Lua file.

Execute menu

Bounces Execute menu
Command Description
Load Source File When a Lua source file has been modified since the last loaded version on the connected target and is not auto-reload mode, this command loads the current version of the Lua file on the connected target.
Reload Source File On Update Toggle the auto-reload mode for the current Lua source file.

Post a Comment