EtherWiki - User contributions [en]

The Barbarella Library

2024-08-22T21:07:24Z

Sstrader:

[https://thebarbarellalibrary.com/ The Barbarella Library] is a website that documents and organizes every edition of the Barbarella comics along with related material such as magazines and artwork.

I originally published the website on 30 Jun 2024 and [https://www.scottdstrader.com/blog/echo/?p=10013 wrote about it on my blog].

[[Category: Projects]]
[[Category: Web sites]]

Main Page

2024-08-22T21:04:55Z

Sstrader:

{{WebSiteStatus}}

Welcome to '''EtherWiki'''. This wiki contains information and help topics for [[:Category:Projects|projects]] and [[:Category:Web sites|web sites]] I had created.

* Android apps
** [[Phonebot]] for Android allows you to create applications directly from your phone.
** [[Argot]] (pronounced 'are-go) is a free Android application that allows you to bookmark locations using GPS.
* Web sites
** [[The Barbarella Library]] is a website that documents and organizes every edition of the Barbarella comics along with related material such as magazines and artwork.
** [[RadioWave]] aggregates schedules for different radio stations to allow listeners to browse all shows across stations by day or hour.
** [[EtherTV]] allows you to create and share streaming video stations by aggregating videos from web sites like YouTube.
** [[EventNett]] is an events calendar modeled after the openness of Wikipedia.
* Web services
** [[ContentMetrics]] is an open service that allows web developers to add content voting to their web sites.

Topics include help with general navigation along with details on using any of the APIs that access the data.

== See also ==

* [[Contact information]]
* [[Credits]]
* [[Privacy policy]]
* [[Server status]]

Main Page

2024-08-22T20:58:46Z

Sstrader:

{{WebSiteStatus}}

Welcome to '''EtherWiki'''. This wiki contains information and help topics for [[:Category:Projects|projects]] and [[:Category:Web sites|web sites]] I had created.

* Android apps
** [[Phonebot]] for Android allows you to create applications directly from your phone.
** [[Argot]] (pronounced 'are-go) is a free Android application that allows you to bookmark locations using GPS.
* Web sites
** [[The Barbarella Library]]
** [[RadioWave]] aggregates schedules for different radio stations to allow listeners to browse all shows across stations by day or hour.
** [[EtherTV]] allows you to create and share streaming video stations by aggregating videos from web sites like YouTube.
** [[EventNett]] is an events calendar modeled after the openness of Wikipedia.
* Web services
** [[ContentMetrics]] is an open service that allows web developers to add content voting to their web sites.

Topics include help with general navigation along with details on using any of the APIs that access the data.

== See also ==

* [[Contact information]]
* [[Credits]]
* [[Privacy policy]]
* [[Server status]]

The Barbarella Library

2024-08-21T22:55:51Z

Sstrader: Created page with "[https://thebarbarellalibrary.com/ The Barbarella Library] is a website that documents and organizes every edition of the Barbarella comics along with related material such as..."

Main Page

2024-08-21T22:15:44Z

Sstrader:

{{WebSiteStatus}}

Welcome to '''EtherWiki'''. This wiki contains information and help topics for [[:Category:Projects|projects]] and [[:Category:Web sites|web sites]] I had created.

* [[Phonebot]] for Android allows you to create applications directly from your phone.
* [[RadioWave]] aggregates schedules for different radio stations to allow listeners to browse all shows across stations by day or hour.
* [[Argot]] (pronounced 'are-go) is a free Android application that allows you to bookmark locations using GPS.
* [[ContentMetrics]] is an open service that allows web developers to add content voting to their web sites.
* [[EtherTV]] allows you to create and share streaming video stations by aggregating videos from web sites like YouTube.
* [[EventNett]] is an events calendar modeled after the openness of Wikipedia.

Topics include help with general navigation along with details on using any of the APIs that access the data.

== See also ==

* [[Contact information]]
* [[Credits]]
* [[Privacy policy]]
* [[Server status]]

Main Page

2024-08-21T22:12:27Z

Sstrader:

Contact information

2022-01-19T14:59:03Z

Sstrader:

* [mailto:sstrader.home@gmail.com Email]
* [[EtherTV]] on [http://twitter.com/ethertvtuner Twitter]
* [[Phonebot]]
** [mailto:gophonebot@gmail.com Email]
** [http://twitter.com/gophonebot Twitter]
* [[RadioWave]] on [http://twitter.com/radiowavetuner Twitter]

Phonebot release schedule

2014-11-08T11:44:03Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|2 Nov 2014
|1.1.22
|2.0.22
|Added: [[Phonebot_developer%27s_reference/Object_reference#Web_view|WebView]] control to display HTML content.
|-
|9 Nov 2012
|1.1.21
|2.0.21
|Added: Support for [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|sending SMS messages]].
|-
|27 Oct 2012
|1.1.20
|2.0.20
|Added: Tablet support. Single [[Phonebot properties|autostart app]] will run on device reboot. Special [[Phonebot_developer%27s_reference/Script_language#Operators_and_literals|escape characters]] supported in code (e.g. quote and newline).
|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Deleting variables and layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]
[[Category:Release schedule]]

Phonebot developer's reference/Object reference

2014-11-05T02:48:01Z

Sstrader: /* Web view */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|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 ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2014-11-05T02:47:34Z

Sstrader: /* Web view */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

The initial URL to load can be set using the [[Using Phonebot display properties|image source property]]. Calling <code>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 ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2014-11-02T22:27:11Z

Sstrader: /* Visual types */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

The initial URL can be set using the [[Using Phonebot display properties|image source property]]. The storage and scale properties are not yet supported.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|The last URL resources loaded for the page.
|}

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>
|
|-
|<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 ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2014-11-02T22:25:56Z

Sstrader: /* Web view */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

The initial URL can be set using the [[Using Phonebot display properties|image source property]]. The storage and scale properties are not yet supported.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|The last URL resources loaded for the page.
|}

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>
|
|-
|<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 ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot release schedule

2014-11-02T22:18:48Z

Sstrader:

Phonebot developer's reference/Object reference

2014-11-02T21:38:42Z

Sstrader: /* Web view */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|The last URL resources loaded for the page.
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>back()</code>
|
|-
|<code>forward()</code>
|
|-
|<code>reload()</code>
|
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|<code>on_update</code>
|A web resource is being loaded. The <code>value</code> of the control is the URL of that resource.
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2014-11-02T21:36:53Z

Sstrader: /* Visual types */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|The last URL resources loaded for the page.
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2014-11-02T21:35:29Z

Sstrader: /* Visual types */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Web view ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Script language

2014-07-21T21:33:19Z

Sstrader: /* Variables and basic types */

== Operators and literals ==

{|class="wikitable"
|-
!Operator
!Description
|-
|<code>+ - * /</code>
|Numeric
|-
|<code>&</code>
|String concatenation
|-
|<code>== != < <= > >=</code>
|Comparison
|-
|<code>! && <nowiki>||</nowiki></code>
|Boolean
|-
|}

Strings:

"Delimited by double quotes."
"Allow \"special characters\" with escape sequences.\nA new line."

--see [http://docs.oracle.com/javase/tutorial/java/data/characters.html Characters] listing valid escape sequences

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

== Variables and basic types ==

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0 /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4) /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9" /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3 /* temp1 = true */

The '''intrinsic data types''' are:

{|class="wikitable"
|-
!Intrinsic type name
!Description
|-
|<code>integer</code>
|No decimal places
|-
|<code>double</code>
|Floating-point
|-
|<code>string</code>
|Double-quote delimited
|-
|<code>boolean</code>
|true or false, non-empty strings and non-zero numbers evaluated as true
|-
|}

Coersion to boolean can be used as a shorthand to test if values are present:

if (name)
// the variable contains data
end

if (values:array.size)
// the array contains items
end

=== Complex types ===

Variables can be [http://en.wikipedia.org/wiki/Type_conversion coerced into different types]. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable <code>temp1</code> being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The '''coercible types''' are:

{|class="wikitable"
|-
!Coercible type name
!Description
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Array|array]]</code>
|A collection of values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>
|A persistent data store
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code>
|A date and time
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#File|file]]</code>
|A file or folder
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code>
|Data formatted as a [http://en.wikipedia.org/wiki/JSON JSON] data structure
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code>
|A collection of associated values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Number|number]]</code>
|An integer or double
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Record|record]]</code>
|A collection of related data from a database
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#String|string]]</code>
|Double-quote delimited
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#XML|xml]]</code>
|Data formatted as [http://en.wikipedia.org/wiki/XML XML]
|-
|}

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1 /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size /* coerce to access the string size, temp2 = 15 */

=== Scope ===

Variables are defined within a specific '''scope'''. A variable's scope determines where it can be accessed.

{|class="wikitable"
|-
!Scope
!Description
|-
|Local
|Visible only within the current script.
|-
|Module
|Visible within any events on the module and any events on controls within the module.
|-
|Application
|Visible within any events on the application and any events across all modules, controls, and services.
|-
|}

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

<code>temp1</code> can be referenced only within the current script. <code>module1.temp1</code> can be referenced within any script within the module and will retain the last value set. <code>application1.temp1</code> can be referenced within any script within the application and will retain the last value set.

== Visual and container types ==

Visual and container objects are anything that the user interacts with. '''Visual types''' include items such as buttons and edit controls; '''container types''' consist of modules and applications. Visual types are also called controls.

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Container_types|Container type]]
!Description
|-
|[[Phonebot_developer%27s_reference/Object_reference#Application|Application]]
|Contains modules and databases
|-
|[[Phonebot_developer%27s_reference/Object_reference#Module|Module]]
|Contains controls
|-
|}

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual type]]/Control
!Description
|-
|Button
|Responds to a user click
|-
|Check box
|Displayed as checked or unchecked
|-
|Drop down list
|
|-
|Edit box
|Accepts typed text
|-
|Image
|Displays an image
|-
|Label
|Displays a message
|-
|List
|Contains a vertical list of text
|-
|Radio button
|Grouped in two or more to offer a single selection
|-
|}

:Note: In computer science, ''type'', ''class'', and ''object'' all have specific definitions. Here, they will be used in the following more general sense:
:*''Type'' - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
:*''Object'' - An object is an instance of a type. A specific integer object may equal <code>5</code> and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to <code>Hello, world!</code>.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have <code>OnClick</code>. Container types have <code>OnOpen</code>, <code>OnClose</code>, and <code>OnService</code>.

=== The this keywords ===

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword <code>this</code>. <code>this</code> enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

<code>this</code> can be used within any object's events including those of applications, services, modules, and controls. In addition, <code>thisapp</code> can be used as a synonym for the currently running application, and <code>thismod</code> can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

The previous example showing scoped variables could be rewritten as follows:

temp1 = "local scope"
edit1.text = temp1
thismod.temp1 = "module scope"
edit1.text = thismod.temp1
thisapp.temp1 = "application scope"
edit1.text = thisapp.temp1

=== Object name collisions ===

Object names are restricted to avoid duplicates based on where they are contained.

* Application names must be unique across all other applications.
* Within an application, module names must be different than the application name, and unique across other modules and services.
* Within an application, service names must be different than the application name, and unique across modules and other services.
* Within a module, control names must be different than the application and module names, and unique across other controls.

{|class="wikitable"
|-
|
|Applications
|Modules
|Services
|Controls
|-
|Application
|X
|
|
|
|-
|Module
|X
|X
|X
|
|-
|Service
|X
|X
|X
|
|-
|Control
|X
|X
|X
|X
|-
|}

== Control structures ==

'''Assignments''' copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

'''Methods''' take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts") /* store the database into a variable */
db_size = db:database.size /* coerce db into a database object and store the size */

Phonebot Plus also provides [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined methods]].

'''Conditionals''' test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
msg = "Negative number"
elseif (temp1 == 0)
msg = "Zero"
elseif (temp1 < 10)
msg = "Positive number, less than 10"
else
msg = "Positive number, 10 or greater"
end

'''Loops''' process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
msg = msg & " " & index
end

'''Comments'''

Both C-style block comments and C++ style inline comments:

/* Test for:
zero
one
*/
if (x == 0 || x == 1)
// Display results
edit.text = "Success!"
end

[[Category:Phonebot]]

Phonebot developer's reference/Script language

2012-11-16T14:37:36Z

Sstrader: /* Variables and basic types */

== Operators and literals ==

{|class="wikitable"
|-
!Operator
!Description
|-
|<code>+ - * /</code>
|Numeric
|-
|<code>&</code>
|String concatenation
|-
|<code>== != < <= > >=</code>
|Comparison
|-
|<code>! && <nowiki>||</nowiki></code>
|Boolean
|-
|}

Strings:

"Delimited by double quotes."
"Allow \"special characters\" with escape sequences.\nA new line."

--see [http://docs.oracle.com/javase/tutorial/java/data/characters.html Characters] listing valid escape sequences

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

== Variables and basic types ==

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0 /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4) /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9" /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3 /* temp1 = true */

The '''intrinsic data types''' are:

{|class="wikitable"
|-
!Intrinsic type name
!Description
|-
|<code>integer</code>
|No decimal places
|-
|<code>double</code>
|Floating-point
|-
|<code>string</code>
|Double-quote delimited
|-
|<code>boolean</code>
|true or false, non-empty strings and non-zero numbers evaluated as true
|-
|}

Coersion to boolean can be used as a shorthand to test if values are present:

if (name) {
// the variable contains data
}

if (values:array.size) {
// the array contains items
}

=== Complex types ===

Variables can be [http://en.wikipedia.org/wiki/Type_conversion coerced into different types]. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable <code>temp1</code> being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The '''coercible types''' are:

{|class="wikitable"
|-
!Coercible type name
!Description
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Array|array]]</code>
|A collection of values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>
|A persistent data store
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code>
|A date and time
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#File|file]]</code>
|A file or folder
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code>
|Data formatted as a [http://en.wikipedia.org/wiki/JSON JSON] data structure
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code>
|A collection of associated values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Number|number]]</code>
|An integer or double
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Record|record]]</code>
|A collection of related data from a database
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#String|string]]</code>
|Double-quote delimited
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#XML|xml]]</code>
|Data formatted as [http://en.wikipedia.org/wiki/XML XML]
|-
|}

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1 /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size /* coerce to access the string size, temp2 = 15 */

=== Scope ===

Variables are defined within a specific '''scope'''. A variable's scope determines where it can be accessed.

{|class="wikitable"
|-
!Scope
!Description
|-
|Local
|Visible only within the current script.
|-
|Module
|Visible within any events on the module and any events on controls within the module.
|-
|Application
|Visible within any events on the application and any events across all modules, controls, and services.
|-
|}

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

<code>temp1</code> can be referenced only within the current script. <code>module1.temp1</code> can be referenced within any script within the module and will retain the last value set. <code>application1.temp1</code> can be referenced within any script within the application and will retain the last value set.

== Visual and container types ==

Visual and container objects are anything that the user interacts with. '''Visual types''' include items such as buttons and edit controls; '''container types''' consist of modules and applications. Visual types are also called controls.

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Container_types|Container type]]
!Description
|-
|[[Phonebot_developer%27s_reference/Object_reference#Application|Application]]
|Contains modules and databases
|-
|[[Phonebot_developer%27s_reference/Object_reference#Module|Module]]
|Contains controls
|-
|}

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual type]]/Control
!Description
|-
|Button
|Responds to a user click
|-
|Check box
|Displayed as checked or unchecked
|-
|Drop down list
|
|-
|Edit box
|Accepts typed text
|-
|Image
|Displays an image
|-
|Label
|Displays a message
|-
|List
|Contains a vertical list of text
|-
|Radio button
|Grouped in two or more to offer a single selection
|-
|}

:Note: In computer science, ''type'', ''class'', and ''object'' all have specific definitions. Here, they will be used in the following more general sense:
:*''Type'' - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
:*''Object'' - An object is an instance of a type. A specific integer object may equal <code>5</code> and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to <code>Hello, world!</code>.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have <code>OnClick</code>. Container types have <code>OnOpen</code>, <code>OnClose</code>, and <code>OnService</code>.

=== The this keywords ===

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword <code>this</code>. <code>this</code> enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

<code>this</code> can be used within any object's events including those of applications, services, modules, and controls. In addition, <code>thisapp</code> can be used as a synonym for the currently running application, and <code>thismod</code> can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

The previous example showing scoped variables could be rewritten as follows:

temp1 = "local scope"
edit1.text = temp1
thismod.temp1 = "module scope"
edit1.text = thismod.temp1
thisapp.temp1 = "application scope"
edit1.text = thisapp.temp1

=== Object name collisions ===

Object names are restricted to avoid duplicates based on where they are contained.

* Application names must be unique across all other applications.
* Within an application, module names must be different than the application name, and unique across other modules and services.
* Within an application, service names must be different than the application name, and unique across modules and other services.
* Within a module, control names must be different than the application and module names, and unique across other controls.

{|class="wikitable"
|-
|
|Applications
|Modules
|Services
|Controls
|-
|Application
|X
|
|
|
|-
|Module
|X
|X
|X
|
|-
|Service
|X
|X
|X
|
|-
|Control
|X
|X
|X
|X
|-
|}

== Control structures ==

'''Assignments''' copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

'''Methods''' take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts") /* store the database into a variable */
db_size = db:database.size /* coerce db into a database object and store the size */

Phonebot Plus also provides [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined methods]].

'''Conditionals''' test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
msg = "Negative number"
elseif (temp1 == 0)
msg = "Zero"
elseif (temp1 < 10)
msg = "Positive number, less than 10"
else
msg = "Positive number, 10 or greater"
end

'''Loops''' process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
msg = msg & " " & index
end

'''Comments'''

Both C-style block comments and C++ style inline comments:

/* Test for:
zero
one
*/
if (x == 0 || x == 1)
// Display results
edit.text = "Success!"
end

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-11-10T16:38:24Z

Sstrader:

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

* email - Send email
* http - Make web requests and retrieve response
* phone - Monitor phone events and send SMS messages
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>. Email is sent using the Postmark Web service. Refer to their [http://postmarkapp.com/privacy-policy privacy policy] for information on how information is used.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names

<code>sms_to</code> - SMS address

<code>sms_text</code> - the SMS content
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.

If <code>sms_to</code> is set, the contents of <code>sms_text</code> will be sent via SMS. Returns two events in the queue containing the following values:

sms_sent,error_code,error_description
sms_received,error_code,error_description

If error_code is 0, error_description will be "OK". Any other response will provide error values.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_delivered</code>
|<code>error_code,error_description</code>
|Generated when a sent SMS messages is delivered
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|Generated when an SMS messages is received
|-
|<code>sms_sent</code>
|<code>error_code,error_description</code>
|Generated when an SMS messages is sent
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-11-10T00:40:37Z

Sstrader: /* Phone events */

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

* email - Send email
* http - Make web requests
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>. Email is sent using the Postmark Web service. Refer to their [http://postmarkapp.com/privacy-policy privacy policy] for information on how information is used.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names

<code>sms_to</code> - SMS address

<code>sms_text</code> - the SMS content
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.

If <code>sms_to</code> is set, the contents of <code>sms_text</code> will be sent via SMS. Returns two events in the queue containing the following values:

sms_sent,error_code,error_description
sms_received,error_code,error_description

If error_code is 0, error_description will be "OK". Any other response will provide error values.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_delivered</code>
|<code>error_code,error_description</code>
|Generated when a sent SMS messages is delivered
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|Generated when an SMS messages is received
|-
|<code>sms_sent</code>
|<code>error_code,error_description</code>
|Generated when an SMS messages is sent
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot release schedule

2012-11-10T00:37:31Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|9 Nov 2012
|1.1.21
|2.0.21
|Added: Support for [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|sending SMS messages]].
|-
|27 Oct 2012
|1.1.20
|2.0.20
|Added: Tablet support. Single [[Phonebot properties|autostart app]] will run on device reboot. Special [[Phonebot_developer%27s_reference/Script_language#Operators_and_literals|escape characters]] supported in code (e.g. quote and newline).
|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Deleting variables and layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-11-08T04:06:15Z

Sstrader: /* Service properties */

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

* email - Send email
* http - Make web requests
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>. Email is sent using the Postmark Web service. Refer to their [http://postmarkapp.com/privacy-policy privacy policy] for information on how information is used.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names

<code>sms_to</code> - SMS address

<code>sms_text</code> - the SMS content
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.

If <code>sms_to</code> is set, the contents of <code>sms_text</code> will be sent via SMS. Returns two events in the queue containing the following values:

sms_sent,error_code,error_description
sms_received,error_code,error_description

If error_code is 0, error_description will be "OK". Any other response will provide error values.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot properties

2012-10-28T23:16:02Z

Sstrader:

'''Auto-start''' configures one or more applications to start when Phonebot starts. If more than one are selected, a menu will display first. When only one application is selected, its [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|autostart system services]] will be started whenever the device is rebooted.

'''Cache''' configures when scripts are parsed when running an application. Applications with long scripts run more responsively if they are compiled before use. The settings are:

* Compile on each use - Turn of compiler caching
* On demand (default) - Compile and cache scripts the first time they run, use the cache on subsequent runs
* Precompile on module open - Compile and cache every script in a module when the module first opens
* Precompile on application open - Compile and cache every script in an application when the application first opens

'''Timeout''' configures the longest that a script can run. If a script runs longer that the timeout, Phonebot will end execution on the current statement.

'''Sensor buffer''' configures the maximum number of sensor events that will be retained in the [[Using Phonebot services|sensor service]] queue. When the queue is filled and new events are added, the oldest events will be deleted from the queue.

'''Retention''' configures the maximum number of log messages that will be kept across all applications.

[[Category:Phonebot]]

Phonebot properties

2012-10-28T23:04:33Z

Sstrader:

'''Auto-start''' configures one or more applications to start when Phonebot starts. If more than one are selected, a menu will display first. When only one application is selected, its autostart system services will be started whenever the device is rebooted.

'''Cache''' configures when scripts are parsed when running an application. Applications with long scripts run more responsively if they are compiled before use. The settings are:

* Compile on each use - Turn of compiler caching
* On demand (default) - Compile and cache scripts the first time they run, use the cache on subsequent runs
* Precompile on module open - Compile and cache every script in a module when the module first opens
* Precompile on application open - Compile and cache every script in an application when the application first opens

'''Timeout''' configures the longest that a script can run. If a script runs longer that the timeout, Phonebot will end execution on the current statement.

'''Sensor buffer''' configures the maximum number of sensor events that will be retained in the [[Using Phonebot services|sensor service]] queue. When the queue is filled and new events are added, the oldest events will be deleted from the queue.

'''Retention''' configures the maximum number of log messages that will be kept across all applications.

[[Category:Phonebot]]

Phonebot release schedule

2012-10-27T19:43:18Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|27 Oct 2012
|1.1.20
|2.0.20
|Added: Tablet support. Single [[Phonebot properties|autostart app]] will run on device reboot. Special [[Phonebot_developer%27s_reference/Script_language#Operators_and_literals|escape characters]] supported in code (e.g. quote and newline).

|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Deleting variables and layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]

Phonebot release schedule

2012-10-27T19:42:56Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|27 Oct 2012
|1.1.20
|2.0.20
|Added: 1.1.20 - Added: Tablet support. Single [[Phonebot properties|autostart app]] will run on device reboot. Special [[Phonebot_developer%27s_reference/Script_language#Operators_and_literals|escape characters]] supported in code (e.g. quote and newline).

|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Deleting variables and layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]

Phonebot developer's reference/Script language

2012-10-27T19:42:34Z

Sstrader: /* Operators and literals */

== Operators and literals ==

{|class="wikitable"
|-
!Operator
!Description
|-
|<code>+ - * /</code>
|Numeric
|-
|<code>&</code>
|String concatenation
|-
|<code>== != < <= > >=</code>
|Comparison
|-
|<code>! && <nowiki>||</nowiki></code>
|Boolean
|-
|}

Strings:

"Delimited by double quotes."
"Allow \"special characters\" with escape sequences.\nA new line."

--see [http://docs.oracle.com/javase/tutorial/java/data/characters.html Characters] listing valid escape sequences

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

== Variables and basic types ==

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0 /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4) /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9" /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3 /* temp1 = true */

The '''intrinsic data types''' are:

{|class="wikitable"
|-
!Intrinsic type name
!Description
|-
|<code>integer</code>
|No decimal places
|-
|<code>double</code>
|Floating-point
|-
|<code>string</code>
|Double-quote delimited
|-
|<code>boolean</code>
|true or false, non-empty strings and non-zero numbers evaluated as true
|-
|}

=== Complex types ===

Variables can be [http://en.wikipedia.org/wiki/Type_conversion coerced into different types]. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable <code>temp1</code> being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The '''coercible types''' are:

{|class="wikitable"
|-
!Coercible type name
!Description
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Array|array]]</code>
|A collection of values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>
|A persistent data store
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code>
|A date and time
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#File|file]]</code>
|A file or folder
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code>
|Data formatted as a [http://en.wikipedia.org/wiki/JSON JSON] data structure
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code>
|A collection of associated values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Number|number]]</code>
|An integer or double
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Record|record]]</code>
|A collection of related data from a database
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#String|string]]</code>
|Double-quote delimited
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#XML|xml]]</code>
|Data formatted as [http://en.wikipedia.org/wiki/XML XML]
|-
|}

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1 /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size /* coerce to access the string size, temp2 = 15 */

=== Scope ===

Variables are defined within a specific '''scope'''. A variable's scope determines where it can be accessed.

{|class="wikitable"
|-
!Scope
!Description
|-
|Local
|Visible only within the current script.
|-
|Module
|Visible within any events on the module and any events on controls within the module.
|-
|Application
|Visible within any events on the application and any events across all modules, controls, and services.
|-
|}

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

<code>temp1</code> can be referenced only within the current script. <code>module1.temp1</code> can be referenced within any script within the module and will retain the last value set. <code>application1.temp1</code> can be referenced within any script within the application and will retain the last value set.

== Visual and container types ==

Visual and container objects are anything that the user interacts with. '''Visual types''' include items such as buttons and edit controls; '''container types''' consist of modules and applications. Visual types are also called controls.

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Container_types|Container type]]
!Description
|-
|[[Phonebot_developer%27s_reference/Object_reference#Application|Application]]
|Contains modules and databases
|-
|[[Phonebot_developer%27s_reference/Object_reference#Module|Module]]
|Contains controls
|-
|}

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual type]]/Control
!Description
|-
|Button
|Responds to a user click
|-
|Check box
|Displayed as checked or unchecked
|-
|Drop down list
|
|-
|Edit box
|Accepts typed text
|-
|Image
|Displays an image
|-
|Label
|Displays a message
|-
|List
|Contains a vertical list of text
|-
|Radio button
|Grouped in two or more to offer a single selection
|-
|}

:Note: In computer science, ''type'', ''class'', and ''object'' all have specific definitions. Here, they will be used in the following more general sense:
:*''Type'' - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
:*''Object'' - An object is an instance of a type. A specific integer object may equal <code>5</code> and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to <code>Hello, world!</code>.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have <code>OnClick</code>. Container types have <code>OnOpen</code>, <code>OnClose</code>, and <code>OnService</code>.

=== The this keywords ===

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword <code>this</code>. <code>this</code> enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

<code>this</code> can be used within any object's events including those of applications, services, modules, and controls. In addition, <code>thisapp</code> can be used as a synonym for the currently running application, and <code>thismod</code> can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

The previous example showing scoped variables could be rewritten as follows:

temp1 = "local scope"
edit1.text = temp1
thismod.temp1 = "module scope"
edit1.text = thismod.temp1
thisapp.temp1 = "application scope"
edit1.text = thisapp.temp1

=== Object name collisions ===

Object names are restricted to avoid duplicates based on where they are contained.

* Application names must be unique across all other applications.
* Within an application, module names must be different than the application name, and unique across other modules and services.
* Within an application, service names must be different than the application name, and unique across modules and other services.
* Within a module, control names must be different than the application and module names, and unique across other controls.

{|class="wikitable"
|-
|
|Applications
|Modules
|Services
|Controls
|-
|Application
|X
|
|
|
|-
|Module
|X
|X
|X
|
|-
|Service
|X
|X
|X
|
|-
|Control
|X
|X
|X
|X
|-
|}

== Control structures ==

'''Assignments''' copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

'''Methods''' take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts") /* store the database into a variable */
db_size = db:database.size /* coerce db into a database object and store the size */

Phonebot Plus also provides [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined methods]].

'''Conditionals''' test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
msg = "Negative number"
elseif (temp1 == 0)
msg = "Zero"
elseif (temp1 < 10)
msg = "Positive number, less than 10"
else
msg = "Positive number, 10 or greater"
end

'''Loops''' process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
msg = msg & " " & index
end

'''Comments'''

Both C-style block comments and C++ style inline comments:

/* Test for:
zero
one
*/
if (x == 0 || x == 1)
// Display results
edit.text = "Success!"
end

[[Category:Phonebot]]

Comparing time value formats

2012-10-06T02:19:30Z

Sstrader:

'''[[Phonebot_developer%27s_reference/Object_reference#Application|Application]] object'''

The <code>now()</code> method returns the current time and is a synonym for <code>datetime.now()</code>.

'''[[Phonebot_developer%27s_reference/Object_reference#Datetime|Datetime]] object'''

The <code>add_duration()</code> method takes a parameter that represents a duration in a single unit of time as <code>DURATION[y|M|d|h|m|s]</code>.

The <code>format()</code> method takes a parameter that uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax].

The <code>format_difference()</code> method formats the datetime value as <code>HH:mm:ss</code>.

'''[[Using_Phonebot_services#Object_reference|Services]]'''

The sensor service <code>minimum_update</code> property takes an integer value in milliseconds.

The timer service <code>duration</code> property takes a value formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>.

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-10-06T02:17:08Z

Sstrader: /* Application */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]].
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-10-06T02:16:52Z

Sstrader: /* Datetime */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]]
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Application|application.now()]].
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-10-06T02:16:06Z

Sstrader: /* Application */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>now()</code>
|Current time. See also [[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime.now()]]
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Script language

2012-08-22T03:34:52Z

Sstrader: /* The this keywords */

== Operators and literals ==

{|class="wikitable"
|-
!Operator
!Description
|-
|<code>+ - * /</code>
|Numeric
|-
|<code>&</code>
|String concatenation
|-
|<code>== != < <= > >=</code>
|Comparison
|-
|<code>! && <nowiki>||</nowiki></code>
|Boolean
|-
|}

Strings:

"Delimited by double quotes."

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

== Variables and basic types ==

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0 /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4) /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9" /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3 /* temp1 = true */

The '''intrinsic data types''' are:

{|class="wikitable"
|-
!Intrinsic type name
!Description
|-
|<code>integer</code>
|No decimal places
|-
|<code>double</code>
|Floating-point
|-
|<code>string</code>
|Double-quote delimited
|-
|<code>boolean</code>
|true or false, non-empty strings and non-zero numbers evaluated as true
|-
|}

=== Complex types ===

Variables can be [http://en.wikipedia.org/wiki/Type_conversion coerced into different types]. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable <code>temp1</code> being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The '''coercible types''' are:

{|class="wikitable"
|-
!Coercible type name
!Description
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Array|array]]</code>
|A collection of values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>
|A persistent data store
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code>
|A date and time
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#File|file]]</code>
|A file or folder
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code>
|Data formatted as a [http://en.wikipedia.org/wiki/JSON JSON] data structure
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code>
|A collection of associated values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Number|number]]</code>
|An integer or double
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Record|record]]</code>
|A collection of related data from a database
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#String|string]]</code>
|Double-quote delimited
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#XML|xml]]</code>
|Data formatted as [http://en.wikipedia.org/wiki/XML XML]
|-
|}

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1 /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size /* coerce to access the string size, temp2 = 15 */

=== Scope ===

Variables are defined within a specific '''scope'''. A variable's scope determines where it can be accessed.

{|class="wikitable"
|-
!Scope
!Description
|-
|Local
|Visible only within the current script.
|-
|Module
|Visible within any events on the module and any events on controls within the module.
|-
|Application
|Visible within any events on the application and any events across all modules, controls, and services.
|-
|}

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

<code>temp1</code> can be referenced only within the current script. <code>module1.temp1</code> can be referenced within any script within the module and will retain the last value set. <code>application1.temp1</code> can be referenced within any script within the application and will retain the last value set.

== Visual and container types ==

Visual and container objects are anything that the user interacts with. '''Visual types''' include items such as buttons and edit controls; '''container types''' consist of modules and applications. Visual types are also called controls.

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Container_types|Container type]]
!Description
|-
|[[Phonebot_developer%27s_reference/Object_reference#Application|Application]]
|Contains modules and databases
|-
|[[Phonebot_developer%27s_reference/Object_reference#Module|Module]]
|Contains controls
|-
|}

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual type]]/Control
!Description
|-
|Button
|Responds to a user click
|-
|Check box
|Displayed as checked or unchecked
|-
|Drop down list
|
|-
|Edit box
|Accepts typed text
|-
|Image
|Displays an image
|-
|Label
|Displays a message
|-
|List
|Contains a vertical list of text
|-
|Radio button
|Grouped in two or more to offer a single selection
|-
|}

:Note: In computer science, ''type'', ''class'', and ''object'' all have specific definitions. Here, they will be used in the following more general sense:
:*''Type'' - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
:*''Object'' - An object is an instance of a type. A specific integer object may equal <code>5</code> and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to <code>Hello, world!</code>.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have <code>OnClick</code>. Container types have <code>OnOpen</code>, <code>OnClose</code>, and <code>OnService</code>.

=== The this keywords ===

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword <code>this</code>. <code>this</code> enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

<code>this</code> can be used within any object's events including those of applications, services, modules, and controls. In addition, <code>thisapp</code> can be used as a synonym for the currently running application, and <code>thismod</code> can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

The previous example showing scoped variables could be rewritten as follows:

temp1 = "local scope"
edit1.text = temp1
thismod.temp1 = "module scope"
edit1.text = thismod.temp1
thisapp.temp1 = "application scope"
edit1.text = thisapp.temp1

=== Object name collisions ===

Object names are restricted to avoid duplicates based on where they are contained.

* Application names must be unique across all other applications.
* Within an application, module names must be different than the application name, and unique across other modules and services.
* Within an application, service names must be different than the application name, and unique across modules and other services.
* Within a module, control names must be different than the application and module names, and unique across other controls.

{|class="wikitable"
|-
|
|Applications
|Modules
|Services
|Controls
|-
|Application
|X
|
|
|
|-
|Module
|X
|X
|X
|
|-
|Service
|X
|X
|X
|
|-
|Control
|X
|X
|X
|X
|-
|}

== Control structures ==

'''Assignments''' copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

'''Methods''' take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts") /* store the database into a variable */
db_size = db:database.size /* coerce db into a database object and store the size */

Phonebot Plus also provides [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined methods]].

'''Conditionals''' test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
msg = "Negative number"
elseif (temp1 == 0)
msg = "Zero"
elseif (temp1 < 10)
msg = "Positive number, less than 10"
else
msg = "Positive number, 10 or greater"
end

'''Loops''' process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
msg = msg & " " & index
end

'''Comments'''

Both C-style block comments and C++ style inline comments:

/* Test for:
zero
one
*/
if (x == 0 || x == 1)
// Display results
edit.text = "Success!"
end

[[Category:Phonebot]]

Phonebot developer's reference/Script language

2012-08-22T03:32:51Z

Sstrader: /* Complex types */

== Operators and literals ==

{|class="wikitable"
|-
!Operator
!Description
|-
|<code>+ - * /</code>
|Numeric
|-
|<code>&</code>
|String concatenation
|-
|<code>== != < <= > >=</code>
|Comparison
|-
|<code>! && <nowiki>||</nowiki></code>
|Boolean
|-
|}

Strings:

"Delimited by double quotes."

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

== Variables and basic types ==

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0 /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4) /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9" /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3 /* temp1 = true */

The '''intrinsic data types''' are:

{|class="wikitable"
|-
!Intrinsic type name
!Description
|-
|<code>integer</code>
|No decimal places
|-
|<code>double</code>
|Floating-point
|-
|<code>string</code>
|Double-quote delimited
|-
|<code>boolean</code>
|true or false, non-empty strings and non-zero numbers evaluated as true
|-
|}

=== Complex types ===

Variables can be [http://en.wikipedia.org/wiki/Type_conversion coerced into different types]. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable <code>temp1</code> being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The '''coercible types''' are:

{|class="wikitable"
|-
!Coercible type name
!Description
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Array|array]]</code>
|A collection of values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>
|A persistent data store
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code>
|A date and time
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#File|file]]</code>
|A file or folder
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code>
|Data formatted as a [http://en.wikipedia.org/wiki/JSON JSON] data structure
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code>
|A collection of associated values
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Number|number]]</code>
|An integer or double
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#Record|record]]</code>
|A collection of related data from a database
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#String|string]]</code>
|Double-quote delimited
|-
|<code>[[Phonebot_developer%27s_reference/Object_reference#XML|xml]]</code>
|Data formatted as [http://en.wikipedia.org/wiki/XML XML]
|-
|}

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1 /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size /* coerce to access the string size, temp2 = 15 */

=== Scope ===

Variables are defined within a specific '''scope'''. A variable's scope determines where it can be accessed.

{|class="wikitable"
|-
!Scope
!Description
|-
|Local
|Visible only within the current script.
|-
|Module
|Visible within any events on the module and any events on controls within the module.
|-
|Application
|Visible within any events on the application and any events across all modules, controls, and services.
|-
|}

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

<code>temp1</code> can be referenced only within the current script. <code>module1.temp1</code> can be referenced within any script within the module and will retain the last value set. <code>application1.temp1</code> can be referenced within any script within the application and will retain the last value set.

== Visual and container types ==

Visual and container objects are anything that the user interacts with. '''Visual types''' include items such as buttons and edit controls; '''container types''' consist of modules and applications. Visual types are also called controls.

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Container_types|Container type]]
!Description
|-
|[[Phonebot_developer%27s_reference/Object_reference#Application|Application]]
|Contains modules and databases
|-
|[[Phonebot_developer%27s_reference/Object_reference#Module|Module]]
|Contains controls
|-
|}

{|class="wikitable"
|-
![[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual type]]/Control
!Description
|-
|Button
|Responds to a user click
|-
|Check box
|Displayed as checked or unchecked
|-
|Drop down list
|
|-
|Edit box
|Accepts typed text
|-
|Image
|Displays an image
|-
|Label
|Displays a message
|-
|List
|Contains a vertical list of text
|-
|Radio button
|Grouped in two or more to offer a single selection
|-
|}

:Note: In computer science, ''type'', ''class'', and ''object'' all have specific definitions. Here, they will be used in the following more general sense:
:*''Type'' - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
:*''Object'' - An object is an instance of a type. A specific integer object may equal <code>5</code> and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to <code>Hello, world!</code>.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have <code>OnClick</code>. Container types have <code>OnOpen</code>, <code>OnClose</code>, and <code>OnService</code>.

=== The this keywords ===

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword <code>this</code>. <code>this</code> enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

<code>this</code> can be used within any object's events including those of applications, services, modules, and controls. In addition, <code>thisapp</code> can be used as a synonym for the currently running application, and <code>thismod</code> can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

=== Object name collisions ===

Object names are restricted to avoid duplicates based on where they are contained.

* Application names must be unique across all other applications.
* Within an application, module names must be different than the application name, and unique across other modules and services.
* Within an application, service names must be different than the application name, and unique across modules and other services.
* Within a module, control names must be different than the application and module names, and unique across other controls.

{|class="wikitable"
|-
|
|Applications
|Modules
|Services
|Controls
|-
|Application
|X
|
|
|
|-
|Module
|X
|X
|X
|
|-
|Service
|X
|X
|X
|
|-
|Control
|X
|X
|X
|X
|-
|}

== Control structures ==

'''Assignments''' copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

'''Methods''' take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts") /* store the database into a variable */
db_size = db:database.size /* coerce db into a database object and store the size */

Phonebot Plus also provides [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined methods]].

'''Conditionals''' test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
msg = "Negative number"
elseif (temp1 == 0)
msg = "Zero"
elseif (temp1 < 10)
msg = "Positive number, less than 10"
else
msg = "Positive number, 10 or greater"
end

'''Loops''' process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
msg = msg & " " & index
end

'''Comments'''

Both C-style block comments and C++ style inline comments:

/* Test for:
zero
one
*/
if (x == 0 || x == 1)
// Display results
edit.text = "Success!"
end

[[Category:Phonebot]]

Phonebot developer's reference

2012-08-22T03:30:16Z

Sstrader:

A reference guide for developing applications with the [[Phonebot]] Android app.

# [[Phonebot developer's reference/Creating applications|Creating applications]] - An overview of the development environment
# [[Phonebot developer's reference/Script language|Script language]] - Details on what the script language provides
# [[Phonebot developer's reference/Object reference|Object reference]] - A catalog of all object properties, methods, and events, including tools such as:
## [[Phonebot_developer%27s_reference/Object_reference#Visual_types|Visual controls]] such as buttons, edit boxes, and lists
## [[Phonebot developer's reference/Object reference/Using Phonebot services|Hardware services]] such as email, GPS, phone, and Web requests
## [[Managing_databases_in_Phonebot_applications#Database|Database]] and [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] objects for persistent storage
## [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects accessing Web service data
# [[Phonebot developer's reference/Sample applications|Sample applications]] - A description of what is contained in each sample application, including:
## Examples of how to use all Phonebot script object types
## An email client
## A Google New and Twitter Web service client
# [[Phonebot developer's reference/Advanced tools|Advanced tools]] - Features available only in Phonebot Plus

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-19T15:43:18Z

Sstrader: /* Service properties */

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

* email - Send email
* http - Make web requests
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>. Email is sent using the Postmark Web service. Refer to their [http://postmarkapp.com/privacy-policy privacy policy] for information on how information is used.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-19T14:45:01Z

Sstrader:

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

* email - Send email
* http - Make web requests
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot release schedule

2012-08-18T20:46:35Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Deleting variables and layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-18T20:39:55Z

Sstrader: /* Service properties */

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
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] array containing a JSON object with a name and a data or path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents retrieved by calling any of the [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file.read()]] methods. Path contains the local path to the file. If path is present, data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}

{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - email addresses separated by commas

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - email addresses separated by commas
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a [[Phonebot_developer%27s_reference/Object_reference#Map|map]] of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-18T20:30:31Z

Sstrader: /* Service properties */

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
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - JSON array containing a JSON object with a Name and a Data or Path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents. Path contains the local path to the file. If Path is present, Data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}
{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - a single email address or an array of email addresses

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - a single email address or an array of email addresses
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

Emails will be received from the address <code>"Phonebot Email Service" pbot.email@gophonebot.com</code>.

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a map of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Sample applications

2012-08-18T20:26:37Z

Sstrader: /* Calculator */

== Agent ==

* Uses <code>[[Phonebot_developer%27s_reference/Object_reference#Application|application.open_application(name)]]</code> to open external processes
* Creates a user <code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code> to save previous commands

== Calculator ==

* Each number key contains the same script in its OnClick event by using [[Phonebot_developer%27s_reference/Script_language#The_this_keywords|the <code>this</code> keyword]].

== Email client ==

* Uses [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service to send emails with attachments.
* Uses [[Phonebot_developer%27s_reference/Object_reference#Module|file dialog]] to browse for attachments from the file system and the [[Phonebot_developer%27s_reference/Object_reference#File|file]] object to read the file.

== Notepad ==

* Creates a user <code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code> to save notes
* Uses the <code>[[Phonebot_developer%27s_reference/Object_reference#Map|map]]</code> object to sort notes
* Uses [[Phonebot_developer%27s_reference/Object_reference#List|<code>list</code> named objects]] to store database records within the visual list
* Uses a [[Phonebot_developer%27s_reference/Advanced_tools#User-defined_methods|user-defined method]] to load notes into the list

== Services ==

* Contains several examples of each type of <code>[[Phonebot_developer%27s_reference/Object_reference#Services|service]]</code>
* The "Twitter feed" module uses an http service object to make a request to the Twitter [https://dev.twitter.com/docs/api/1/get/search search Web service]. When the [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s [[Phonebot_developer%27s_reference/Creating_applications#Services|<code>OnService</code> event]] fires, the <code>[[Phonebot_developer%27s_reference/Object_reference#Json|json]]</code> object is used to parse the event data and fill a [[Phonebot_developer%27s_reference/Object_reference#List|list]] with the search results.

Depending on the hardware, sensors can produce a large number of events. If the application freezes when reading sensor data, try setting the Phonebot "Sensor buffer" to a lower value.

== Time tracker ==

Keep track of how much time you spend on different tasks. Create task types to categorize tasks. Use timer to start and stop tasks. View a list of every task or a summary of how much time was spent on each task type.

* Creates two user <code>[[Phonebot_developer%27s_reference/Object_reference#Database|database]]</code>s
* Uses <code>[[Phonebot_developer%27s_reference/Object_reference#Datetime|datetime]]</code> objects to manage timestamps and durations
* The application contains [[Phonebot_developer%27s_reference/Script_language#Scope|application scoped variables]]
* The "Menu" module uses module scoped variables

[[Category:Phonebot]]

Phonebot release schedule

2012-08-18T20:23:22Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|18 Aug 2012
|1.1.19
|2.0.19
|Added: [[Phonebot_developer%27s_reference/Object_reference/Using_Phonebot_services#Service_properties|Email]] service for sending emails with attachments. HTTP service supports the POST method. Fixed: Layout issues with Script Manager. Sped up [[Phonebot_developer%27s_reference/Object_reference/Using_the_Phonebot_file_object|file]] object read methods. [[Phonebot_developer%27s_reference/Object_reference#Module|Module]] event size now returns the correct value.
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-08-18T20:22:15Z

Sstrader: /* Module */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-18T20:14:09Z

Sstrader: /* Object reference */

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
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

=== Service properties ===

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - JSON array containing a JSON object with a Name and a Data or Path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents. Path contains the local path to the file. If Path is present, Data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}
{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - a single email address or an array of email addresses

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - a single email address or an array of email addresses
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a map of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Using Phonebot services

2012-08-18T20:13:16Z

Sstrader: /* Object reference */

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
* phone - Monitor phone events
* sensor - Monitor hardware sensors
* timer - Alert at specific intervals

When a service is updated, events are fired in the following order:

# The service's <code>OnUpdate</code> event fires
# The [[Phonebot_developer%27s_reference/Object_reference#Application|application]]'s <code>OnService</code> event fires
# The current [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s <code>OnService</code> event fires

Each Service stores its update data in a queue. The methods <code>get_event()</code> and <code>pop_event()</code> access the next event in the queue; <code>event_size</code> returns how many events exist; <code>clear_events()</code> clears the queue.

The maximum number of sensor events that will be retained in the queue is controlled by the "Sensor buffer" [[Phonebot properties|Phonebot property]]. The "Sensor buffer" value, the sensor service's "Minimum update frequency" value, and the amount of script within each <code>OnUpdate</code> and <code>OnService</code> event will determine how responsive your application is when reading sensor data. If updates are sluggish, try reducing the buffer size.

A [[Phonebot_developer%27s_reference/Object_reference#Module|module]]'s show_file_dialog() method can be considered a module-level service.

== Service lifecycle ==

A service's properties, methods, and the application state affect that service's lifetime as the following diagram illustrates:

[[Image:phonebot.service-lifecycle.png]]

A service will start running:

* When its start() method is called
* If its autostart property is set to true, immediately after the application starts

A service will stop running:

* When its stop() method is called
* If its system property is set to false, when the application loses focus
* If its system property is set to true, when the application exits

== Object reference ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>auto_start</code>
|Read-only boolean. Set to true to start the service as soon as the application starts.
|-
|<code>event_size</code>
|Read-only. The number of events in the queue. When monitoring multiple services, this property can be used in <code>on_service</code> events to determine which service was updated.
|-
|<code>name</code>
|Read-only.
|-
|<code>system</code>
|Read-only boolean. Set to true to have the service run even when the application has lost focus.
|-
|<code>text</code>
|Read-only.
|}

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>value = get_property(name)</code>
|Retrieve the value of a custom property (see below).
|-
|<code>event = pop_event()</code>
|Retrieve and delete the next event in the queue.
|-
|<code>set_property(name, value)</code>
|Set the value of a custom property (see below).
|-
|<code>start()</code>
|Start the service.
|-
|<code>stop()</code>
|Stop the service.
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_service</code>
|
|-
|}

In addition to the common properties, methods, and events, each service may have custom properties accessible from the get_property() and set_property() methods:

{|class="wikitable sortable"
|-
!Service
!Properties
!Description
|-
|<code>email</code>
|<code>attachments</code> - JSON array containing a JSON object with a Name and a Data or Path field. Name contains the file name with an extension denoting the content type. Data contains the byte array of the file contents. Path contains the local path to the file. If Path is present, Data will be ignored. Either of the following is valid:

{"name":"%name%", "path":"%path%"}
{"name":"%name%", "data":"%data%"}

<code>body</code>

<code>cc</code> - a single email address or an array of email addresses

<code>reply_to</code> - a single email address

<code>subject</code>

<code>to</code> - a single email address or an array of email addresses
|Send an email. Returns a single event in the queue containing the following values:

http_response,error_code,error_description

If http_response is 200, error_code will be 0 and error_description will be "OK". Any other response will provide error values.

The following restrictions are put on sending emails:

{|class="wikitable"
|-
!Restriction
!Phonebot
!Phonebot Plus
|-
|Number of emails in past 24 hour
|5
|100
|-
|Number of recipients per email
|1
|20
|}

|-
|<code>http</code>
|<code>data</code> - the data sent for a POST

<code>headers</code> - a map of header names to values

<code>method</code> - the request method: GET or POST

<code>url</code> - the URL
|Makes a request to a URL. Returns a single event in the queue containing the response.
|-
|<code>phone</code>
|<code>events</code> - array of event names
|Monitors one or more phone events. Returns an event containing a comma-delimited list of values beginning with the event name (e.g. <code>data_activity,4</code>). The range of each value is dependent on the event.
|-
|<code>sensor</code>
|<code>minimum_update</code> - time between updates in milliseconds
<code>sensors</code> - array of sensor names
|Monitors one or more hardware sensors. Returns an event containing a comma-delimited list of values beginning with the sensor name (e.g. <code>orientation,60.0,-28.0,3.0</code>). The range of each value is dependent on the sensor.
|-
|<code>timer</code>
|<code>duration</code> - time between updates, formatted as <code>h:m:s</code>, <code>m:s</code>, or <code>s</code>
|Fire the update events at regular intervals. The event will first fire immediately after the service is started. Returns an event containing the <code>datetime</code> value when the update happened.
|-
|}

Events can be accessed and parsed in the following manner:

HTTP:

event = http_service.pop_event()
// query with XPath
items = event:xml.query("//root/item")
// read json data
root = event:json.get_element("root")
items = event:json.get_element("item")

Sensor:

event = sensor_service.pop_event()
event = event:string.split(",")
name = event:array.get_element(0)
// get values from index 1 and greater

Timer:

event = timer_service.pop_event()
event = event:datetime.format("HH:mm:ss")

=== Phone events ===

The phone service can be configured to return any combination of phone events. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>call_forwarding</code>
|<code>cfi</code>
|boolean
|-
|<code>call_state</code>
|<code>state,incoming_number</code>
|state: 0 - idle, 1 - ringing, 2 - off hook
|-
|<code>cell_location</code>
|<code>"cdma",base_station_id,base_station_latitude,base_station_longitude,system_id,network_id</code>
<code>"gsm",lac,cid</code>
|
|-
|<code>data_activity</code>
|<code>direction</code>
|0 - none, 1 - in, 2 - out, 3 - in/out, 4 - dormant
|-
|<code>data_connection_state</code>
|<code>state,network_type</code>
|state: 0 - disconnected, 1 - connecting, 2 - connected, 3 - suspended
|-
|<code>message_waiting</code>
|<code>mwi</code>
|boolean
|-
|<code>service_state</code>
|<code>is_manual_selection,operator_alpha_long,operator_alpha_short,operator_numeric,roaming,state</code>
|state: 0 - in service, 1 - out of service, 2 - emergency only, 3 - power off
|-
|<code>signal_strengths</code>
|<code>cdma_ecio,evdo_dbm,evdo_ecio,evdo_snr,gsm_bit_error_rate,gsm_signal_strength,is_gsm</code>
|
|-
|<code>sms_received</code>
|<code>timestamp,originating_address,message_body</code>
|
|}

--[http://developer.android.com/reference/android/telephony/PhoneStateListener.html PhoneStateListener]

=== Sensor events ===

The sensor service can be configured to return any combination of sensor types. Each type has its own name and data format as described below:

{|class="wikitable sortable"
|-
!Name
!Structure of event value
(actual values are prefixed with the name, i.e. <code>name,value1,value2,...</code>)
!Description
|-
|<code>accelerometer</code>
|<code>x,y,z</code>
|Acceleration in meters/second^2
|-
|<code>gps</code>
|<code>latitude,longitude,accuracy,altitude,bearing,speed</code>
|
|-
|<code>gravity</code>
|<code>x,y,z</code>
|Gravity in meters/second^2
|-
|<code>gyroscope</code>
|<code>x,y,z</code>
|Angular speed in radian/second
|-
|<code>light</code>
|<code>l</code>
|Ambient light in [http://en.wikipedia.org/wiki/Lux lux units]
|-
|<code>linear_acceleration</code>
|<code></code>
|Acceleration in meters/second^2
|-
|<code>magnetic_field</code>
|<code>x,y,z</code>
|Magnetic field in [http://en.wikipedia.org/wiki/Tesla_(unit) micro-Teslas]
|-
|<code>orientation</code>
|<code>azimuth,pitch,roll</code>
|Measured in degrees. 0=North, 90=East, 180=South, 270=West; -180..180; -90..90
|-
|<code>pressure</code>
|<code>p</code>
|Atmospheric pressure in [http://en.wikipedia.org/wiki/Bar_(unit) millibars]
|-
|<code>proximity</code>
|<code>p</code>
|Proximity in centimeters
|-
|<code>rotation_vector</code>
|<code></code>
|
|-
|<code>temperature</code>
|<code></code>
|
|-
|}

--[http://developer.android.com/reference/android/hardware/SensorEvent.html#values SensorEvent values]

[[Category:Phonebot]]

Phonebot developer's reference/Object reference/Managing databases in Phonebot applications

2012-08-07T11:29:10Z

Sstrader: Managing databases in Phonebot applications moved to Phonebot developer's reference/Object reference/Managing databases in Phonebot applications

A [[Phonebot]] 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 the [[Phonebot_developer%27s_reference/Object_reference#Application|Application]] object to manage databases in an application
** database_exists(), delete_database(), get_database(), and get_database_names()
* Use the [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object to manage fields and records in a database
* Use the [[Phonebot_developer%27s_reference/Object_reference#Record|Record]] object to manage field values in a record

Phonebot Plus provides a [[Phonebot_developer%27s_reference/Advanced_tools#Database_browser|database browser]] to manage schema and data.

== Object reference ==

=== Database ===

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

=== Record ===

Represents a record in a specific database.

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>
|
|-
|}

== 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")

[[Category:Phonebot]]

Managing databases in Phonebot applications

2012-08-07T11:29:10Z

Sstrader: Managing databases in Phonebot applications moved to Phonebot developer's reference/Object reference/Managing databases in Phonebot applications

#REDIRECT [[Phonebot developer's reference/Object reference/Managing databases in Phonebot applications]]

Phonebot developer's reference/Object reference

2012-08-04T17:03:43Z

Sstrader: /* XML */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-08-04T17:00:14Z

Sstrader: /* XML */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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 and 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>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot developer's reference/Object reference

2012-08-04T16:52:24Z

Sstrader: /* Json */

== Container types ==

=== Application ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>description</code>
|
|-
|<code>name</code>
|Read-only
|-
|<code>startup</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_close</code>
|
|-
|<code>on_open</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>close_application()</code>
|
|-
|<code>close_module()</code>
|
|-
|<code>value = database_exists(name)</code>
|Returns true if the database exists
|-
|<code>delete_database(name)</code>
|Deletes the [[Phonebot_developer%27s_reference/Object_reference#Database|database]] and all records in it.
|-
|<code>database = get_database(name)</code>
|Retrieve the database and create if it doesn't exist.
|-
|<code>array = get_database_names()</code>
|
|-
|<code>log(message)</code>
|Log a user event.
|-
|<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.
|-
|<code>open_application(name)</code>
|Open a Phonebot application by passing <code>pbot:APPLICATION_NAME</code>. Open other Android applications using their Intent URI:
* [http://developer.android.com/guide/appendix/g-app-intents.html Intents List: Invoking Google Applications on Android Devices]
* [http://developer.android.com/guide/publishing/publishing.html#UriSummary Summary of URI formats] for the Android market
|-
|<code>open_module(name)</code>
|
|-
|}

=== Module ===

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<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>
|Read-only array
|-
|<code>name</code>
|Read-only
|-
|<code>orientation [ vertical <nowiki>|</nowiki> horizontal ]</code>
|Read-only
|-
|<code>text</code>
|
|-
|}

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

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_open</code>
|
|-
|<code>on_close</code>
|
|-
|<code>on_service</code>
|Fires after any service's <code>on_update</code> fires.
|-
|}

== Visual types ==

See [[Using display properties]] for details on accessing display properties.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>enabled</code>
|true/false
|-
|<code>group</code>
|Read-only
|-
|<code>layout_height [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>layout_width [ fill_container <nowiki>|</nowiki> wrap_content ]</code>
|Read-only
|-
|<code>name</code>
|Read-only
|-
|<code>text</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 ]</code>
|Read-only
|-
|<code>visible</code>
|true/false
|-
|}

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_click</code>
|
|-
|}

=== Button ===

=== Check box ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

=== Drop down list ===

See [[Phonebot_developer%27s_reference/Object_reference#List|List]].

=== Edit box ===

Events

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>on_update</code>
|Fires after any change to the contents
|-
|}

=== Image ===

The image control uses the [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|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.

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>selected_index</code>
|Read-only
|-
|<code>selected_item</code>
|Read-only. The text of column zero of the selected row
|-
|<code>size</code>
|Read-only
|-
|}

Methods

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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_item(item)</code>
|Add and item to the list and return the index of the added item.
|-
|<code>clear()</code>
|
|-
|<code>delete_item(index)</code>
|
|-
|<code>item = get_item(row, col)</code>
|
|-
|<code>array = get_items(col)</code>
|
|-
|<code>set_item(row, col, value)</code>
|
|-
|<code>sort(type, col)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>value</code>
|true/false
|-
|}

== Services ==

See [[Phonebot developer's reference/Object reference/Using Phonebot services#Object_reference|Using Phonebot services: Object reference]]

== Variables ==

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>(value)</code>
|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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = add_element(element)</code>
|Add an element to the end of the collection.
|-
|<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>boolean = exists(value)</code>
|
|-
|<code>element = get_element(index)</code>
|Get the value at <code>index</code>.
|-
|<code>string = join(delimiter)</code>
|Join the array elements with delimiter and return the string.
|-
|<code>reverse()</code>
|
|-
|<code>index = set_element(index, value)</code>
|Set the element. Log runtime error if it doesn't exist.
|-
|<code>sort(type)</code>
|0 = alpha-numeric by value, 1 = numeric by value
|-
|<code>unique()</code>
|Delete any duplicate values. The first value will be retained and subsequent duplicates will be deleted.
|-
|}

=== Database ===

See [[Managing_databases_in_Phonebot_applications#Database|Managing databases: Database]].

=== Datetime ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>add_duration(formatted_value)</code>
|Add a duration to the datetime. Values are strings in the format:
DURATION[y|M|d|h|m|s]
|-
|<code>datetime = difference(datetime)</code>
|Calculates the difference between the two <code>datetime</code>s.
|-
|<code>string = format(format)</code>
|Uses the Java [http://download.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html#datepattern date format pattern syntax]
|-
|<code>format_difference()</code>
|Formats the <code>datetime</code> value returned by <code>difference()</code>. Formatted as <code>HH:mm:ss</code>. The result is only valid within a 24 hour range.
|-
|<code>now()</code>
|
|-
|'''TBD''' <code>parse(value, format)</code>
|Set the datetime to the string <code>value</code> formatted as <code>format</code>.
|-
|}

=== File ===

See [[Phonebot developer's reference/Object reference/Using the Phonebot file object|Using the Phonebot file object]]

=== Json ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|
|-
|<code>size</code>
|Read-only. Returns the size of the JSON array.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!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>
|Returns the named value or a JSON array.
|-
|<code>string = get_record(index)</code>
|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.
|}

=== 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

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|
|-
|}

Methods

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

=== Number ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|
|
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>number = average(array)</code>
|Sets the value to the average and returns that value.
|-
|<code>number = fraction()</code>
|x.y returns 0.y
|-
|<code>number = integer()</code>
|x.y returns x
|-
|'''TBD''' <code>number = random(min, max)</code>
|A random number between min and max
|-
|<code>number = round()</code>
|< x.5 returns x; >= x.5 returns x + 1
|-
|}

=== Record ===

See [[Managing_databases_in_Phonebot_applications#Record|Managing databases: Record]].

=== String ===

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>size</code>
|Read-only
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>index = index_of(string)</code>
|
|-
|<code>string = replace_all(value, replacement)</code>
|
|-
|<code>array = split(delimiter)</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()]].
|-
|}

=== XML ===

Parse and query XML and HTML data.

Properties

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>is_valid</code>
|Read-only.
|-
|<code>name</code>
|Read-only. Element name.
|-
|<code>size</code>
|Read-only. Number of children.
|-
|<code>text</code>
|Read-only. Text content.
|-
|}

Methods

{|class="wikitable sortable"
|-
!Syntax
!Description
|-
|<code>map = get_attributes()</code>
|The element's attribute names mapped to their values.
|-
|<code>xml = get_child(index)</code>
|
|-
|<code>xml <nowiki>|</nowiki> array = query(xpath)</code>
|Query the document using [http://www.w3.org/TR/xpath/ XPath] and return XML or an array of attribute values. Use <code>xml.is_valid</code> to determine whether XML or an array has been returned. Uses a subset of the syntax supported by the [http://docs.oracle.com/javase/1.5.0/docs/api/javax/xml/xpath/package-summary.html 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']
|-
|}

[[Category:Phonebot]]

Phonebot release schedule

2012-08-04T16:46:22Z

Sstrader:

Changes made for each version of the [[Phonebot]] Android app.

{|class="wikitable"
|-
!Date
!Phonebot version
!Phonebot Plus version
!Description
|-
|4 Aug 2012
|1.1.18
|2.0.18
|Added: Edit methods added to the [[Phonebot_developer%27s_reference/Object_reference#Json|JSON]] and [[Phonebot_developer%27s_reference/Object_reference#XML|XML]] objects. Easily create and update these formats to use for internal storage or with Web service calls.
|-
|19 Jul 2012
|1.1.17
|2.0.17
|Added: [[Using the Phonebot file object|File object]] to manage files and folders, supports create, delete, copy, move, and multiple forms of read and write; added [[Phonebot_developer%27s_reference/Object_reference#Array|array.byte_to_string()]] and [[Phonebot_developer%27s_reference/Object_reference#String|string.to_byte_array()]] to convert binary data; Fixed: local variable sometime not initialized when method called multiple times.
|-
|29 Jun 2012
|1.1.16
|2.0.16
|Added: Inserting controls, display icons in graph when the [[Phonebot_developer%27s_reference/Object_reference#Application|application]] or [[Phonebot_developer%27s_reference/Object_reference#Module|module]] is closed from script, context menu item to set startup module; Fixed: title in property pages, script not displaying in [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus).
|-
|24 Jun 2012
|1.1.15
|2.0.15
|Added: module with controls larger than screen will scroll; Fixed: logging filter not updating, pasted controls missing their script events, writeable script builder not scrolling.
|-
|20 Jun 2012
|1.1.14
|2.0.14
|Fixed: Crash when running in the background and memory is cleared; [[Phonebot_developer%27s_reference/Object_reference#Application|notifications]] with different modules opening the same module; [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] sometimes not getting created.
|-
|7 Jun 2012
|1.1.13
|2.0.13
|Added: Show startup module as application icon; report when empty events fire during [[Phonebot_developer%27s_reference/Advanced_tools#Script_debugger|debug]] (Phonebot Plus). Fixed: Crash when using non-system [[Using Phonebot services|services]] with a [[Phonebot_developer%27s_reference/Object_reference#Application|notification]].
|-
|2 Jun 2012
|1.1.12
|2.0.12
|Added: File dialog for setting an [[Phonebot_developer%27s_reference/Object_reference#Image|image]] control's image source (Phonebot Plus only); <code>show_file_dialog()</code> method for [[Phonebot_developer%27s_reference/Object_reference#Module|module]]s.
|-
|22 May 2012
|1.1.11
|2.0.11
|Added: [[Phonebot properties|Auto-start property]] for specifying applications to run on startup. Fixed: Intermittent crash when debugging applications with services.
|-
|7 May 2012
|1.1.10
|2.0.10
|Fixed: Parser errors; deprecated properties displaying in script builders.
|-
|1 May 2012
|1.1.9
|2.0.9
|Added: Database script generation for Phonebot Plus. Fixed: Parser errors on some [[Phonebot_developer%27s_reference/Script_language#Scope|scoped variables]] and some [[Phonebot_developer%27s_reference/Script_language#Complex_types|coerced]] method calls.
|-
|29 Apr 2012
|1.1.8
|2.0.8
|Added: get_display() and set_display() methods for modules and controls (see [[Using display properties]] on the wiki), clipboard menu for layout editor. Fixed: parsing negative numbers.
|-
|21 Apr 2012
|1.1.7
|2.0.7
|Added: [[Phonebot_developer%27s_reference/Advanced_tools#Display_properties|image control]]. Fixed: module not displaying correctly when opened from [[Phonebot_developer%27s_reference/Object_reference#Application|notify() method]], hiding invisible controls
|-
|9 Apr 2012
|
|2.0.6
|Fixed: crash when using the application list clipboard menu.
|-
|5 Apr 2012
|1.1.6
|2.0.5
|Added: [[Using_Phonebot_services#Phone_events|phone service]] to monitor phone and SMS events; [[Phonebot_developer%27s_reference/Object_reference#Application|application]].database_exists() method and [[Phonebot_developer%27s_reference/Object_reference#Database|database]].exists property.
|-
|31 Mar 2012
|1.1.5
|2.0.4
|Added: [[Phonebot_developer%27s_reference/Object_reference#Application|application]].notify() method to create status bar notifications. Fixed: running modules from edit mode.
|-
|28 Mar 2012
|1.1.4
|2.0.3
|Updated: services can now run when the application loses focus. See "[[Using Phonebot services]]" in the wiki. [[Phonebot_developer%27s_reference/Object_reference#Database|Database]] object delete fixed and clear added.

Note: The service lifecycle has changed and has been more fully defined in this version. Some existing applications may need to be updated.
|-
|
|1.1.3
|2.0.2
|Added: add, edit, and toggle [[Phonebot_developer%27s_reference/Script_language#Control_structures|comments]] in script. Fixed: crash when parsing invalid script.
|-
|
|1.1.2
|2.0.1
|Added: [[Phonebot_developer%27s_reference/Object_reference#List|list]].get_items(); [[Phonebot_developer%27s_reference/Object_reference#Array|array]].exists(). Fixed: property and method sorting in script builders; saving list control padding.
|-
|7 Mar 2012
|1.1.1
|2.0.0
|Release of [[Phonebot developer's reference/Advanced tools|Phonebot Plus]]. Merge functionality with Phonebot.
|-
|29 Oct 2011
|1.0.0
|
|Release of Phonebot.
|}

[[Category:Phonebot]]