Phonebot developer's reference/Object reference

Container types

Application

Properties

Syntax	Description
description
name	Read-only
startup	Read-only
text

Events

Syntax	Description
on_close
on_open
on_service	Fires after any service's on_update fires.

Methods

Syntax	Description
close_application()
close_module()
value = database_exists(name)	Returns true if the database exists
delete_database(name)	Deletes the database and all records in it.
database = get_database(name)	Retrieve the database and create if it doesn't exist.
array = get_database_names()
log(message)	Log a user event.
notify(title, text, module)	Display a status bar notification. The title will be used as the ticker text and title. The module is the name of the module to open when the users selects the notification.
open_application(name)	Open a Phonebot application by passing pbot:APPLICATION_NAME. Open other Android applications using their Intent URI: Intents List: Invoking Google Applications on Android Devices Summary of URI formats for the Android market
open_module(name)

Module

See Using display properties for details on accessing display properties.

Properties

Syntax	Description
gravity [ bottom | center_horizontal | center_vertical | left | right | top ], default center_horizontal | center_vertical	Read-only array
name	Read-only
orientation [ vertical | horizontal ]	Read-only
text

Events

Syntax	Description
on_open
on_close
on_service	Fires after any service's on_update fires.

Visual types

See Using display properties for details on accessing display properties.

Properties

Syntax	Description
enabled	true/false
group	Read-only
layout_height [ fill_container | wrap_content ]	Read-only
layout_width [ fill_container | wrap_content ]	Read-only
name	Read-only
text
type [ button | check | drop_down_list | edit | image | label | list | radio ]	Read-only
visible	true/false

Events

Syntax	Description
on_click

Check box

Properties

Syntax	Description
value	true/false

Drop down list

See List.

Edit box

Events

Syntax	Description
on_update	Fires after any change to the contents

Image

The image control uses the display properties configure what image is displayed and how it is displayed.

List

Properties

Syntax	Description
selected_index	Read-only
selected_item	Read-only. The text of column zero of the selected row
size	Read-only

Methods

col values can be either zero, for the display value, or a non-numeric value to retrieve the previously set named data value.

Syntax	Description
index = add_item(item)	Add and item to the list and return the index of the added item.
clear()
delete_item(index)
item = get_item(row, col)
array = get_items(col)
set_item(row, col, value)
sort(type, col)	0 = alpha-numeric by value, 1 = numeric by value

/* Add 10 rows */
for (index = 0; index < 10; index = index + 1)
    list1.add_item("New item " & index)
end

/* Set and get the string displayed in the 5th row */
list1.set_item(4, 0, "New text for the row")     /* Note: the row must already exist. */
row_val = list1.get_item(4, 0)                   /* will retrieve "New item 4" */

/* Set and get the a named data value for the 5th row */
list1.set_item(4, "my data", "hidden value")     /* Note: the row must already exist. */
list1.set_item(4, "more data", "another value")  /* Note: the row must already exist. */
row_val = list1.get_item(4, "my data")           /* will retrieve "hidden value" */

Radio button

Properties

Syntax	Description
value	true/false

Services

See Using Phonebot services: Object reference

Variables

Properties

Syntax	Description
(value)	Tacit, set/return value by default

Array

Manage a collection of values. Values are stored in the order they are added; sorting reorders and eliminates the original order.

Properties

Syntax	Description
size

Methods

Syntax	Description
index = add_element(element)	Add an element to the end of the collection.
clear()
delete_element(index)
boolean = exists(value)
element = get_element(index)	Get the value at index.
string = join(delimiter)	Join the array elements with delimiter and return the string.
reverse()
index = set_element(index, value)	Set the element. Log runtime error if it doesn't exist.
sort(type)	0 = alpha-numeric by value, 1 = numeric by value
unique()	Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.

Database

A database is a collection of data accessed by a unique name. Databases map to tables in SQL. Database records are accessed by their zero-based index. Fields within records are accessed by their zero-based index or by their field name.

• Use Application to manage databases in an application
• Use Database to manage fields and records in a database
• Use Record to manage field values in a record

Properties

Syntax	Description
exists	True if the database has fields defined.
field_size	The number of fields in the database.
name
size	The number of records in the database.

Methods

Syntax	Description
index = add_field(name)	Returns zero-based index. -1 if the field cannot be added.
record = add_record()
clear()
delete_field(index | name)	Delete the field. The values in the associated field in every record in the database will be deleted. This includes those records currently referenced by variables. The index value of the remaining fields will change if those fields have a higher index value than the field being deleted.
delete_record(index | record)
name = get_field_info(index) index = get_field_info(name)	Logs error if index or name does not exist.
array = get_field_names()
record = get_record(index)	Logs error if no record exits at the zero-based index.
record = get_record_by_id(id)	Get the record based on its unique ID. Retrieved from record.id.

Usage:

/* Create a database and record */
db = application1.get_database("contacts")
db:database.add_field("name")
db:database.add_field("email")
first_rec = db:database.add_record()
first_rec:record.set_field("name", "Joe Bot")
first_rec:record.set_field("email", "jbot@android.com")

/* Loop through all fields in the database */
for (field_index = 0; field_index < db:database.field_size; field_index = field_index + 1)
    field_name = db:database.get_field(field_index)
end

/* Loop through all records in a database */
for (index = 0; index < db:database.size; index = index + 1)
    rec = db:database.get_record(index)
    name = rec:record.get_field("name")
    email = rec:record.get_field("email")
    for (field_index = 0; field_index < db:database.field_size; field_index = field_index + 1)
        field_value = rec:record.get_field(field_index)
    end
end

/* Delete the new record and database */
db:database.delete_record(first_rec)
application1.delete_database("contacts")

Datetime

Properties

Syntax	Description

Methods

Syntax	Description
add_duration(formatted_value)	Add a duration to the datetime. Values are strings in the format: DURATION[y|M|d|h|m|s]
datetime = difference(datetime)	Calculates the difference between the two datetimes.
string = format(format)	Uses the Java date format pattern syntax
format_difference()	Formats the datetime value returned by difference(). Formatted as HH:mm:ss. The result is only valid within a 24 hour range.
now()
TBD parse(value, format)	Set the datetime to the string value formatted as format.

Json

Properties

Syntax	Description
is_valid
size	Read-only. Returns the size of the Json array.

Methods

Syntax	Description
string = get_element(name)	Returns the named value or a Json array.
string = get_record(index)	Returns a value or Json object at the index.

Map

Manage a collection of names mapped to values. Pairs are stored in the order they are added; sorting reorders and eliminates the original order.

Properties

Syntax	Description
size

Methods

Syntax	Description
index = add_named_element(name, value)	Add an element to the end of the collection.
add_names(array)
clear()
delete_element(name)
boolean = exists(name)
value = get_element(name)	Get the value mapped by name.
name = get_name(index)	Get the name at index.
array = get_names()
value = get_value(index)	Get the value at index.
array = get_values()
string = join_names(delimiter)	Join the names with delimiter and return the string.
string = join_values(delimiter)	Join the values with delimiter and return the string.
reverse()
index = set_element(name, value)	Set the element. Log runtime error if it doesn't exist.
sort(type)	0 = alpha-numeric by value, 1 = numeric by value, 2 = alpha-numeric by name, 3 = numeric by name

Number

Properties

Syntax	Description

Methods

Syntax	Description
number = average(array)	Sets the value to the average and returns that value.
number = fraction()	x.y returns 0.y
number = integer()	x.y returns x
TBD number = random(min, max)	A random number between min and max
number = round()	< x.5 returns x; >= x.5 returns x + 1

Record

Represents a record in a specific database.

Properties

Syntax	Description
id	The unique ID for the record. Read-only.

Methods

Syntax	Description
field = get_field(index | name)
array = get_fields()
set_field(index | name, value)

String

Properties

Syntax	Description
size	Read-only

Methods

Syntax	Description
index = index_of(string)
string = replace_all(value, replacement)
array = split(delimiter)
string = substring(start_index, end_index)

XML

Parse and query XML and HTML data.

Properties

Syntax	Description
is_valid	Read-only.
name	Read-only. Element name.
size	Read-only. Number of children.
text	Read-only. Text content.

Methods

Syntax	Description
map = get_attributes()	The element's attribute names mapped to their values.
xml = get_child(index)
xml | array = query(xpath)	Query the document using XPath and return XML or an array of attribute values. Use xml.is_valid to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the Java XPath library. The following location path expressions are supported: /foo/bar //bar /foo/bar/* /for/@id (returns array) /foo/bar/text() (returns array) Predicates are not supported: /foo[@bar='bat']