Phonebot developer's reference/Creating applications
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.
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.
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 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.
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, its property page is displayed.
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 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 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
- Loop - Repeat script based on a counter or based on whether a test remains true This creates a
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:
- The scope is either local, the current module, or the application
- The variable name
- A coercible type that determines what properties are available
- 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:
- The control name. The controls Text and Name properties will be displayed for clarity.
- The control type is displayed for clarity and cannot be selected.
- 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 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
pop_event() access the next event in the queue and
event_size returns how many events exist.
The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" Phonebot property. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each
OnService event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.