Phonebot developer's reference/Creating applications

Application basics

Applications consist of an application object, one or more visible modules, and optionally one or more background services. The application is the container for the modules and services. It manages when modules are displayed and when services should run.

The simplest sample application is the Calculator. To run it, from the application list long click on Calculator and select Run from the context menu. To stop it, click the Android menu button and select Stop and you will be returned to the application list.

Note: Phonebot obeys the Android back button but always provides menu items for navigation. The menu items are: Stop, Close, Save, and Cancel. This is done so that you can cancel out of any change by clicking Cancel instead of Save.

The running Calculator application

To edit the Calculator, long click and select Edit. This will open the application editor and display the Modules and Services tabs. To edit the module, long click on the image of the module and select Edit. This will open that module in the module editor.

The Calculator application in the application editor

The calculator module in the module editor

Every object in an application is configured through that object's properties. Properties are accessed either from the context menu or, when an object is being edited, from the main menu at the bottom of the screen. The properties page presents (1) an object's properties, which specify values such as display text or layout size and (2) an object's events, which contain script to run when something happens to the object such as it getting clicked or updated.

The calculator module properties page

The most commonly used event is the OnClick event that all visual controls have. This will fire when the user clicks on the object. The script within the event can perform actions on other controls, the current module, any services, or the application itself. The script language provides basic types and control structures.

The script editor displaying the contents of the "equals" button's OnClick event

Modules and controls

Just as the application is a container for modules and services, a module is a container for controls. Controls are added by selecting "Add control >" and selecting from one of the control types. Once a control type is selected, the property page is displayed.

The add controls menu

Controls are arranged and sized based on the module's Orientation and Gravity properties and the controls' Layout width and Layout height properties. Orientation will make controls flow from top to bottom or left to right; Gravity will align controls relative to the modlule's borders. Neighboring controls can be grouped together to provide different Orientation and Gravity values than the module's. The most common use of this is to have the module Orientation arrange groups from top to bottom, but have controls within group arranged from left to right. Controls that are grouped together will be surrounded by a dashed line in the module editor.

Note: Only neighboring controls can be grouped together.

The group list displays groups and what controls are contained

Controls in a group must be adjacent. Controls already in a different group cannot be selected.

The context menu for controls allows you to move them up or down in the module. When moving a control that neighbors a group, the control will move over the group. When moving the first or last control in a group, the entire group will move in the requested direction.

Scripts

Scripts are run when an object event is fired. The Phonebot script language is used to automate tasks within the application. Example of possible tasks are:

• Set the text in an edit box or read the selected item in a list
• Search a string for values
• Store and sort values in an array
• Store values in a database
• Read orientation values from a service
• Read Web requests from a service

Script can be typed directly into the Advanced tab of the script editor. However, to simplify development, several visual builders are available in the main Editor tab. The builders generate script from developer selections and guarantee that it is valid. The available builders are:

• Assignment - Assign values to variables, set control properties
• Method - Call a method to perform and action such as opening a module or getting the current date
• Conditional - Test if a value is true and execute script based on the result. This creates a if-then-else structure.
• Loop - Repeat script based on a counter or based on whether a test remains true This creates a for loop.

The Assignment builder

The Method builder

The Conditional builder

The Loop builder

When assigning a value, the developer can write to either an existing variable or to a control property. When reading a value, they can read from a new or existing variable, control property, literal value, or an equation.

Variables have four fields to configure:

1. The scope is either local, the current module, or the application
2. The variable name
3. A coercible type that determines what properties are available
4. The property

Note: When accessing data from a variable that is not a complext type, the type is "variable" and the property is "value".

Controls (this includes the application, module, and visual controls) have two fields to configure:

1. The control name. The controls Text and Name properties will be displayed for clarity.
2. The control type is displayed for clarity and cannot be selected.
3. The property

Literals are entered as free-form text. Numbers, true, and false will be displayed as they are; anything else will be surrounded by double-quotes and treated as a string.

Equations are entered as free-form text. This will be used for calculations such as 5 + edit.text or tests such as list.size > 10. Use quotes for literal strings: "listing " & db.size & " records".

Services

Services are non-visual components that monitor different environment states and trigger an event when the state changes. The available services are:

• http - Make web requests
• sensor - Monitor hardware sensors
• timer - Alert at specific intervals

When a service is updated, its OnUpdate event fires, then the application's OnService event fires, and finally the current module's OnService event fires.

Each Service stores its update data in a queue. The methods get_event() and pop_event() access the next event in the queue and event_size returns how many events exist.