Difference between revisions of "Phonebot developer's reference/Object reference"

From EtherWiki
Jump to: navigation, search
(→‎Module)
(→‎Web view)
 
(34 intermediate revisions by the same user not shown)
Line 72: Line 72:
 
|<code>notify(title, text, module)</code>
 
|<code>notify(title, text, module)</code>
 
|Display a status bar notification. The <code>title</code> will be used as the ticker text and title. The <code>module</code> is the name of the module to open when the users selects the notification.
 
|Display a status bar notification. The <code>title</code> will be used as the ticker text and title. The <code>module</code> is the name of the module to open when the users selects the notification.
 +
|-
 +
|<code>now()</code>
 +
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
 
|-
 
|-
 
|<code>open_application(name)</code>
 
|<code>open_application(name)</code>
Line 93: Line 96:
 
!Syntax
 
!Syntax
 
!Description
 
!Description
 +
|-
 +
|<code>event_size</code>
 +
|Read-only. The number of events in the queue.
 
|-
 
|-
 
|<code>gravity [ bottom <nowiki>|</nowiki> center_horizontal <nowiki>|</nowiki> center_vertical <nowiki>|</nowiki> left <nowiki>|</nowiki> right <nowiki>|</nowiki> top ]</code>, default <code>center_horizontal <nowiki>|</nowiki> center_vertical</code>
 
|<code>gravity [ bottom <nowiki>|</nowiki> center_horizontal <nowiki>|</nowiki> center_vertical <nowiki>|</nowiki> left <nowiki>|</nowiki> right <nowiki>|</nowiki> top ]</code>, default <code>center_horizontal <nowiki>|</nowiki> center_vertical</code>
Line 106: Line 112:
 
|
 
|
 
|-
 
|-
 +
|}
 +
 +
Methods
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>size = clear_events()</code>
 +
|Delete all events and return how many were deleted.
 +
|-
 +
|<code>event = get_event()</code>
 +
|Retrieve the next event in the queue.
 +
|-
 +
|<code>event = pop_event()</code>
 +
|Retrieve and delete the next event in the queue.
 +
|-
 +
|<code>show_file_dialog(path, filter, includeFiles)</code>
 +
|Display a file browser dialog. If an item is selected, the module's on_service event will fire. The selected item will be contained in the module's event queue.
 +
* path - the path to the initial folder or file
 +
* filter - an array of file masks, values can be:
 +
** *xxx - match the end of a file name
 +
** xxx* - match the beginning of a file name
 +
** xxx - match the file name exactly
 +
* includeFile - boolean, true to list files, false to exclude files and ignore the filter
 +
 +
See [[Using the Phonebot file object]] for managing files.
 +
 +
See [[Using Phonebot services]] for information on application-level services.
 
|}
 
|}
  
Line 127: Line 163:
  
 
== Visual types ==
 
== Visual types ==
 +
 +
See [[Using display properties]] for details on accessing display properties.
  
 
Properties
 
Properties
Line 153: Line 191:
 
|
 
|
 
|-
 
|-
−
|<code>type [ button <nowiki>|</nowiki> check <nowiki>|</nowiki> drop_down_list <nowiki>|</nowiki> edit <nowiki>|</nowiki> image <nowiki>|</nowiki> label <nowiki>|</nowiki> list <nowiki>|</nowiki> radio ]</code>
+
|<code>type [ button <nowiki>|</nowiki> check <nowiki>|</nowiki> drop_down_list <nowiki>|</nowiki> edit <nowiki>|</nowiki> image <nowiki>|</nowiki> label <nowiki>|</nowiki> list <nowiki>|</nowiki> radio <nowiki>|</nowiki> web_view ]</code>
 
|Read-only
 
|Read-only
 
|-
 
|-
Line 216: Line 254:
  
 
Properties
 
Properties
 +
 +
The text property can contain a semi-colon-delimited list of values to populate the list.
  
 
{|class="wikitable sortable"
 
{|class="wikitable sortable"
Line 291: Line 331:
 
|true/false
 
|true/false
 
|-
 
|-
 +
|}
 +
 +
=== Web view ===
 +
 +
The initial URL to load can be set using the [[Using Phonebot display properties|image source property]]. Calling <code>my_web_view.set_display("image", "source", url)</code> loads a new URL. The image storage and scale properties are not yet supported.
 +
 +
Properties
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>value</code>
 +
|The last URL resource loaded for the page. This will be updated each time <code>on_update</code> fires.
 +
|}
 +
 +
Methods
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>back()</code>
 +
|Go to the previous page in the history.
 +
|-
 +
|<code>forward()</code>
 +
|Go to the next page in the history.
 +
|-
 +
|<code>reload()</code>
 +
|Reload the current page.
 +
|}
 +
 +
Events
 +
 +
{|class="wikitable sortable"
 +
|-
 +
!Syntax
 +
!Description
 +
|-
 +
|<code>on_click</code>
 +
|The web view is clicked.
 +
|-
 +
|<code>on_update</code>
 +
|A web resource is being loaded. The <code>value</code> of the control is the URL of that resource. Setting <code>value</code> while a resource is being loaded overrides the original resource.
 
|}
 
|}
  
 
== Services ==
 
== Services ==
  
−
See [[Using_Phonebot_services#Object_reference|Using Phonebot services: Object reference]]
+
See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]
  
 
== Variables ==
 
== Variables ==
Line 339: Line 425:
 
|<code>clear()</code>
 
|<code>clear()</code>
 
|
 
|
 +
|-
 +
|<code>string = byte_to_string()</code>
 +
|Convert an array of bytes to a string. C.f. [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]].
 
|-
 
|-
 
|<code>delete_element(index)</code>
 
|<code>delete_element(index)</code>
Line 368: Line 457:
 
=== Database ===
 
=== 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.
+
See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].
−
 
 
−
* Use [[Phonebot_developer%27s_reference/Object_reference#Application|Application]] to manage databases in an application
 
−
* Use [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] to manage fields and records in a database
 
−
* Use [[Phonebot_developer%27s_reference/Object_reference#Record|Record]] to manage field values in a record
 
−
 
 
−
Properties
 
−
 
 
−
{|class="wikitable sortable"
 
−
|-
 
−
!Syntax
 
−
!Description
 
−
|-
 
−
|<code>exists</code>
 
−
|True if the database has fields defined.
 
−
|-
 
−
|<code>field_size</code>
 
−
|The number of fields in the database.
 
−
|-
 
−
|<code>name</code>
 
−
|
 
−
|-
 
−
|<code>size</code>
 
−
|The number of records in the database.
 
−
|-
 
−
|}
 
−
 
 
−
Methods
 
−
 
 
−
{|class="wikitable sortable"
 
−
|-
 
−
!Syntax
 
−
!Description
 
−
|-
 
−
|<code>index = add_field(name)</code>
 
−
|Returns zero-based index. -1 if the field cannot be added.
 
−
|-
 
−
|<code>record = add_record()</code>
 
−
|
 
−
|-
 
−
|<code>clear()</code>
 
−
|
 
−
|-
 
−
|<code>delete_field(index <nowiki>|</nowiki> name)</code>
 
−
|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.
 
−
|-
 
−
|<code>delete_record(index <nowiki>|</nowiki> record)</code>
 
−
|
 
−
|-
 
−
|<code>name = get_field_info(index)</code>
 
−
<code>index = get_field_info(name)</code>
 
−
|Logs error if index or name does not exist.
 
−
|-
 
−
|<code>array = get_field_names()</code>
 
−
|
 
−
|-
 
−
|<code>record = get_record(index)</code>
 
−
|Logs error if no record exits at the zero-based index.
 
−
|-
 
−
|<code>record = get_record_by_id(id)</code>
 
−
|Get the record based on its unique ID. Retrieved from <code>record.id</code>.
 
−
|-
 
−
|}
 
−
 
 
−
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 ===
 
=== Datetime ===
Line 496: Line 494:
 
|-
 
|-
 
|<code>now()</code>
 
|<code>now()</code>
−
|
+
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
 
|-
 
|-
 
|'''TBD''' <code>parse(value, format)</code>
 
|'''TBD''' <code>parse(value, format)</code>
Line 502: Line 500:
 
|-
 
|-
 
|}
 
|}
 +
 +
=== File ===
 +
 +
See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]
  
 
=== Json ===
 
=== Json ===
Line 516: Line 518:
 
|-
 
|-
 
|<code>size</code>  
 
|<code>size</code>  
−
|Read-only. Returns the size of the Json array.
+
|Read-only. Returns the size of the JSON array.
 
|-
 
|-
 
|}
 
|}
Line 526: Line 528:
 
!Syntax
 
!Syntax
 
!Description
 
!Description
 +
|-
 +
|<code>value = delete_element(name)</code>
 +
|Delete the name/value pair and return the deleted object.
 +
|-
 +
|<code>value = delete_record(index)</code>
 +
|Delete the JSON object at the specified index and return the deleted object.
 
|-
 
|-
 
|<code>string = get_element(name)</code>
 
|<code>string = get_element(name)</code>
−
|Returns the named value or a Json array.
+
|Returns the named value or a JSON array.
 
|-
 
|-
 
|<code>string = get_record(index)</code>
 
|<code>string = get_record(index)</code>
−
|Returns a value or Json object at the index.
+
|Returns a value or JSON object at the index.
 
|-
 
|-
 +
|<code>set_element(name, value)</code>
 +
|Add the name/value pair to the JSON object.
 +
|-
 +
|<code>string = set_record(index, value)</code>
 +
|Add the JSON value to a JSON array at the specified index.
 
|}
 
|}
  
Line 645: Line 658:
 
=== Record ===
 
=== Record ===
  
−
Represents a record in a specific [[Phonebot_developer%27s_reference/Object_reference#Database|database]].
+
See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].
−
 
 
−
Properties
 
−
 
 
−
{|class="wikitable sortable"
 
−
|-
 
−
!Syntax
 
−
!Description
 
−
|-
 
−
|<code>id</code>
 
−
|The unique ID for the record. Read-only.
 
−
|-
 
−
|}
 
−
 
 
−
Methods
 
−
 
 
−
{|class="wikitable sortable"
 
−
|-
 
−
!Syntax
 
−
!Description
 
−
|-
 
−
|<code>field = get_field(index <nowiki>|</nowiki> name)</code>
 
−
|
 
−
|-
 
−
|<code>array = get_fields()</code>
 
−
|
 
−
|-
 
−
|<code>set_field(index <nowiki>|</nowiki> name, value)</code>
 
−
|
 
−
|-
 
−
|}
 
  
 
=== String ===
 
=== String ===
Line 709: Line 692:
 
|<code>string = substring(start_index, end_index)</code>
 
|<code>string = substring(start_index, end_index)</code>
 
|
 
|
 +
|-
 +
|<code>array = to_byte_array()</code>
 +
|Convert the string to an array of their decimal value representation. C.f. [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]].
 
|-
 
|-
 
|}
 
|}
Line 733: Line 719:
 
|-
 
|-
 
|<code>text</code>
 
|<code>text</code>
−
|Read-only. Text content.
+
|Text content.
 
|-
 
|-
 
|}
 
|}
Line 743: Line 729:
 
!Syntax
 
!Syntax
 
!Description
 
!Description
 +
|-
 +
|<code>value = add_child(xml)</code>
 +
|Append the XML as the last child and return true/false.
 +
|-
 +
|<code>value = create_element(name)</code>
 +
|Create an empty element and return true/false.
 +
|-
 +
|<code>value = delete_attribute(name)</code>
 +
|Delete the named attribute and return its value.
 +
|-
 +
|<code>xml = delete_child(index)</code>
 +
|Delete the child at the specified index and return its value.
 
|-
 
|-
 
|<code>map = get_attributes()</code>
 
|<code>map = get_attributes()</code>

Latest revision as of 02:48, 5 November 2014

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.
now() Current time. See also datetime.now().
open_application(name) Open a Phonebot application by passing pbot:APPLICATION_NAME. Open other Android applications using their Intent URI:
open_module(name)

Module

See Using display properties for details on accessing display properties.

Properties

Syntax Description
event_size Read-only. The number of events in the queue.
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

Methods

Syntax Description
size = clear_events() Delete all events and return how many were deleted.
event = get_event() Retrieve the next event in the queue.
event = pop_event() Retrieve and delete the next event in the queue.
show_file_dialog(path, filter, includeFiles) Display a file browser dialog. If an item is selected, the module's on_service event will fire. The selected item will be contained in the module's event queue.
  • path - the path to the initial folder or file
  • filter - an array of file masks, values can be:
    • *xxx - match the end of a file name
    • xxx* - match the beginning of a file name
    • xxx - match the file name exactly
  • includeFile - boolean, true to list files, false to exclude files and ignore the filter

See Using the Phonebot file object for managing files.

See Using Phonebot services for information on application-level services.

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 | web_view ] Read-only
visible true/false

Events

Syntax Description
on_click

Button

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.

Label

List

Properties

The text property can contain a semi-colon-delimited list of values to populate the list.

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

Web view

The initial URL to load can be set using the image source property. Calling my_web_view.set_display("image", "source", url) loads a new URL. The image storage and scale properties are not yet supported.

Properties

Syntax Description
value The last URL resource loaded for the page. This will be updated each time on_update fires.

Methods

Syntax Description
back() Go to the previous page in the history.
forward() Go to the next page in the history.
reload() Reload the current page.

Events

Syntax Description
on_click The web view is clicked.
on_update A web resource is being loaded. The value of the control is the URL of that resource. Setting value while a resource is being loaded overrides the original resource.

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()
string = byte_to_string() Convert an array of bytes to a string. C.f. string.to_byte_array().
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

See Managing databases: Database.

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() Current time. See also application.now().
TBD parse(value, format) Set the datetime to the string value formatted as format.

File

See Using the Phonebot file object

Json

Properties

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

Methods

Syntax Description
value = delete_element(name) Delete the name/value pair and return the deleted object.
value = delete_record(index) Delete the JSON object at the specified index and return the deleted object.
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.
set_element(name, value) Add the name/value pair to the JSON object.
string = set_record(index, value) Add the JSON value to a JSON array at the specified 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

See Managing databases: Record.

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)
array = to_byte_array() Convert the string to an array of their decimal value representation. C.f. array.byte_to_string().

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 Text content.

Methods

Syntax Description
value = add_child(xml) Append the XML as the last child and return true/false.
value = create_element(name) Create an empty element and return true/false.
value = delete_attribute(name) Delete the named attribute and return its value.
xml = delete_child(index) Delete the child at the specified index and return its value.
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']
Retrieved from "http://ether.scottdstrader.com/index.php?title=Phonebot_developer%27s_reference/Object_reference&oldid=2088"