Version 23 of AndroWish: Documentation

Updated 2014-02-03 14:15:09 by chw

This page is intended as a place to document the capabilities of the custom commands offered by the AndroWish, the Tcl/Tk port to Android (excellent work, chw!). In the true Wiki spirit you are invited to extend this documentation. (You may have, already (chw definitely has): this information was harvested from the AndroWish page!)

There are three Android-specific commands:

  1. borg - control and interact with the Android OS.
  2. rfcomm - transfer data over a Bluetooth serial port profile; akin to the TCL socket command.
  3. sdltk - exposure of the SDL2 (Simple DirectMedia Layer) Android-related API.

Documentation is provided in the order specified.


Name

borg - control and interact with the Android OS.

Synopsis

borg cmd ?arg ...?

Description

This command integrates the capabilities of Tcl/Tk with an Android OS by way of several subcommands. These allow Tcl/Tk to go where it has never gone before by querying and controlling Bluetooth functionality, OS notifications (including device vibration and even speach), location information, etc.

Bluetooth-Related Commands

borg bluetooth devices
Returns a list suited for the "array set" command containing the Bluetooth address and friendly name of all paired Bluetooth devices.
borg bluetooth state
Returns the current Bluetooth state: on or off.
borg bluetooth scanmode
Returns the current Bluetooth scan mode (off, passive, visible, connectable, or on).
borg bluetooth myaddress
Returns the Bluetooth address of the local default Bluetooth adapter.
borg remoteaddress address
Returns the friendly name for the given Bluetooth address.

Network-Related Commands

borg networkinfo
Returns the current state of the network: none, wifi, mobile gsm, etc.

Destkop-Related Commands

borg shortcut add name-of-shortcut script-to-run ?png-icon-as-base-64-string?
Adds an icon to the desktop, with the name-of-shortcut specified. The script, specified as script-to-run must use an absolute path must be readable by the user id under which the AndroWish package has been registered by the Android installer. The last (optional) parameter png-icon-as-base-64-string allows the icon graphic to be specified. If not provided, the AndroWish icon (Alladin's lamp) is used.
borg shortcut delete name-of-shortcut
Deletes an icon from desktop (depends on Android launcher support).

Notification-Related Commands

borg notification add id title text
Adds a notification with title and text into the Android notification area. The integer id, specified by the caller, is used to identify the notification on deletion.
borg notification delete ?id?
Deletes a notification identified that was created with the id specified. If no id is provided, all notifications are deleted.
borg vibrate ms
Turns on the vibration motor for integer ms milliseconds.
borg beep
Plays the notification sound.
borg speak text
Gets the Android to read out the string text.

Location-Related Commands

borg location start ?minrate-in-ms? ?min-dist-in-m?
Begins acquiring location data via the Android OS (which may choose to use GPS, network info, etc.).
borg location stop
Ends location data acquisition.
borg location get
Returns the location data (an an array set form) where the key is the location source. Location updates trigger a virtual event <<LocationUpdate>> (currently untested) which is sent to all toplevel widgets. These toplevel event-handlers should, in turn, invoke borg location get to refresh their knowledge.

General

borg activity action uri type ?categories? ?arguments? ?callback?
This a very flexible command that allows extensive access to the Android OS and other applications. categories and arguments are optional lists. callback is the name of the procedure that is evaluated when the activity action is complete. arguments are key-value pairs where the values are mapped to Java strings by default. If the key is a 2-element list made up of a data type indicator (int, byte, short, char, long, float, double, Uri) followed by the key, the value is converted to that data type. See below for some examples of this command. (?? categories argument ??)

borg activity Examples

Sample code to open a browser on this wiki:

     borg activity android.intent.action.VIEW http://wiki.tcl.tk

Sample code to capture an image (only makes thumbnails - there are resizing problems):

    proc callback {retcode action uri mimetype categories data} {
        if {$retcode == -1} {
            # SUCCESS
            array set result $data
            if {[info exists result(data)]} {
                myphoto configure -data $result(data)
            }
        }
    }
    package require Img
    image create photo myphoto
    borg activity android.media.action.IMAGE_CAPTURE {} {} {} {} callback

Sample code to capture an image, which works better but requires a file on external storage:

    proc callback {filename retcode action uri mimetype categories data} {
        if {$retcode == -1} {
            # SUCCESS
            myphoto configure -file $filename
            catch {file delete -force $filename}
        }
    }
    package require Img
    image create photo myphoto
    set filename [file join $env(EXTERNAL_FILES) myphoto.jpeg]
    borg activity android.media.action.IMAGE_CAPTURE {} {} {} \
       [list {Uri output} file://$filename] [list callback $filename]

Reading barcodes using the http://code.google.com/p/zxing barcode scanner (which needs to be be installed on your device):

    proc barcode_read {code action uri type cat data} {
        array set result $data
        if {[info exists result(SCAN_RESULT)]} {
            # that is the barcode
            # result(SCAN_RESULT_FORMAT) is the barcode format
        }
    }

    borg activity com.google.zxing.client.android.SCAN {} {} {} {} barcode_read

Name

rfcomm - transfer data over a Bluetooth serial port profile; akin to the TCL socket command.

Synopsis

This command is used to transfer data over Bluetooth's serial port profile (SPP or SP). The arguments used are nearly identical to the TCL socketcommand. It returns a client or server channel handle that may be used with gets, read, puts, and close. For client channels, the remote address must be given as a one- or two-element list: the first element is the Bluetooth address, and the (optional) second element is the UUID of the remote service. For server channels, the first element is the UUID, and the optional second element is the friendly name of the service. Server mode functionality has not yet been verified.

Description


Name

(More info required here - written by a novice!)

sdltk - exposure of the SDL2 (Simple DirectMedia Layer) Android-related API.

Synopsis

This command is used to control portions of the Android system that the SDL2 framework exposes. Actual data processing for this framework is achieved by having handlers for virtual events.

Description

sdltk powerinfo
Returns a list of key-value pairs describing the state of the battery.
sdltk accelerometer on|off
Turns the device accelerometer on and off. Creates a top-level virtual event <<Accelerometer>>.
sdltk textinput ?on|off ?x y??
Returns the state of the virtual keyboard or switches the virtual keyboard on or off. The optional coordinate pair is a hint for the system where the insertion cursor is displayed in screen coordinates. This allows the system to pan the application's screen in order to display the insertion cursor when the virtual keyboard is active.

Events

Using the sdltk framework usually requires liberal use of virtual event handlers. The virtual events include:

<<Accelerometer>>
Event associated with the accelerometer (activated with sdltk accelerometer on). %s is the accelerometer axis and %x is the accelerometer value.
<<FingerDown>>
A touch event.
<<FingerUp>>
A touch completion event.
<<FingerMotion>>
A touch movement (sliding) event. The fields %x and %y are substituted with the finger position scaled to {0...9999}, %X and %Y with the difference scaled to {0...9999}, %t with the pressure scaled to {0...9999}, and %s with the finger identifier {1...10}. These substitutions are performed for all finger related touch events.

Events related to the APP life cycle

These events are direct translations from SDL events. They are reported to toplevel widgets only.

<<LowMemory>>
System is in low memory situation
<<Terminating>>
APP is terminating
<<WillEnterBackground>>
APP's screen will be put in background
<<DidEnterBackground>>
APP's screen is in the background
<<WillEnterForeground>>
APP's screen will be put in foreground
<<DidEnterForeground>>
APP's screen is in the foreground

Other events

These events are generated for/by certain borg related commands. They are reported to toplevel widgets only.

<<LocationUpdate>>
Location information has been updated and can be read out using borg location get.
<<NetworkInfo>>
Network state has changed and can be read out using borg networkinfo.
<<Bluetooth>>
Bluetooth state has changed and can be read out using borg bluetooth state.

Revision History

26/01/2014 LWS - creation from AndroWish entries - with lots left out, possible misinterpretation, etc. A momentary editing collision with chw: sorry!
02/02/2014 LWS - updated borg shortcut add with info from AndroWish Feature Requests and modified a portion of the barcode reading example
03/02/2014 chw - updated sdltk command description, added more event descriptions